Events and Callbacks

A feature that exposes key events to notify developers when important changes occur, allowing for seamless integration with data-binding and UI update mechanisms.

Overview

This section covers the events provided by the control to allow developers to hook into its internal state changes. The primary events are ValueChanged and PropertyChanged, which notify subscribers when the numeric value changes or when any bound property is updated. These events facilitate responsive, event-driven programming and integration with data-binding frameworks.

Event Overview Table

Event Name	Description	Trigger Condition	Usage Scenario
ValueChanged	Fired whenever the control’s numeric value is updated, either via user interaction or programmatic changes.	After any successful change to the Value property	Updating dependent UI elements, logging, or calculations
PropertyChanged	Implements the INotifyPropertyChanged interface; notifies subscribers of changes to any public property, which is essential for data binding scenarios.	When any bindable property changes its value	Integrating with MVVM frameworks or data-binding in forms

---

Code Examples and Integration

The following code examples illustrate how to integrate and respond to the control’s events in a .NET WinForms application.

Example 1: Subscribing to the ValueChanged Event

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;
using SiticoneNetFrameworkUI.Helpers.Enum;

public class ValueChangedDemoForm : Form
{
    public ValueChangedDemoForm()
    {
        this.Text = "ValueChanged Event Demo";
        this.Width = 400;
        this.Height = 200;
        
        // Create an instance of the control.
        var numericUpDown = new SiticoneUpDown
        {
            Minimum = 0M,
            Maximum = 100M,
            Value = 25M,
            Increment = 5M,
            DecimalPlaces = 0,
            InputType = InputType.WholeNumbers,
            EnableDirectInput = true,
            Location = new System.Drawing.Point(50, 50)
        };

        // Subscribe to the ValueChanged event.
        numericUpDown.ValueChanged += NumericUpDown_ValueChanged;

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

    private void NumericUpDown_ValueChanged(object sender, EventArgs e)
    {
        var control = sender as SiticoneUpDown;
        MessageBox.Show("The new value is: " + control.Value, "ValueChanged Event");
    }

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

Example 2: Handling PropertyChanged for Data Binding

using System;
using System.ComponentModel;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;
using SiticoneNetFrameworkUI.Helpers.Enum;

public class PropertyChangedDemoForm : Form
{
    private Label valueLabel;
    
    public PropertyChangedDemoForm()
    {
        this.Text = "PropertyChanged Event Demo";
        this.Width = 400;
        this.Height = 200;
        
        // Create an instance of the control.
        var numericUpDown = new SiticoneUpDown
        {
            Minimum = 0M,
            Maximum = 100M,
            Value = 50M,
            Increment = 5M,
            DecimalPlaces = 0,
            InputType = InputType.WholeNumbers,
            EnableDirectInput = true,
            Location = new System.Drawing.Point(50, 50)
        };

        // Create a label to display the current value.
        valueLabel = new Label
        {
            Location = new System.Drawing.Point(50, 100),
            Width = 200,
            Font = new System.Drawing.Font("Segoe UI", 10f)
        };

        // Subscribe to the PropertyChanged event.
        numericUpDown.PropertyChanged += NumericUpDown_PropertyChanged;

        // Add controls to the form.
        this.Controls.Add(numericUpDown);
        this.Controls.Add(valueLabel);
    }

    private void NumericUpDown_PropertyChanged(object sender, PropertyChangedEventArgs e)
    {
        var control = sender as SiticoneUpDown;
        // Update the label whenever the Value property changes.
        if (e.PropertyName == "Value")
        {
            valueLabel.Text = "Current Value: " + control.Value.ToString("F" + control.DecimalPlaces);
        }
    }

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

Example 3: Integrating with MVVM-style Patterns

For developers using a Model-View-ViewModel (MVVM) approach, the PropertyChanged event can help ensure that changes in the control are propagated to the ViewModel.

using System;
using System.ComponentModel;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;
using SiticoneNetFrameworkUI.Helpers.Enum;

public class NumericUpDownViewModel : INotifyPropertyChanged
{
    private decimal numericValue;
    public event PropertyChangedEventHandler PropertyChanged;

    public decimal NumericValue
    {
        get { return numericValue; }
        set
        {
            if (numericValue != value)
            {
                numericValue = value;
                OnPropertyChanged("NumericValue");
            }
        }
    }

    protected virtual void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

public class MVVMDemoForm : Form
{
    private NumericUpDownViewModel viewModel;

    public MVVMDemoForm()
    {
        this.Text = "MVVM Integration Demo";
        this.Width = 400;
        this.Height = 200;

        // Initialize the ViewModel.
        viewModel = new NumericUpDownViewModel { NumericValue = 30M };

        // Create and configure the numeric up/down control.
        var numericUpDown = new SiticoneUpDown
        {
            Minimum = 0M,
            Maximum = 100M,
            Value = viewModel.NumericValue,
            Increment = 5M,
            DecimalPlaces = 0,
            InputType = InputType.WholeNumbers,
            EnableDirectInput = true,
            Location = new System.Drawing.Point(50, 50)
        };

        // Subscribe to the ValueChanged event to update the ViewModel.
        numericUpDown.ValueChanged += (s, e) =>
        {
            viewModel.NumericValue = numericUpDown.Value;
        };

        // Optionally, bind the ViewModel back to UI components.
        var valueLabel = new Label
        {
            Location = new System.Drawing.Point(50, 100),
            Width = 200,
            Text = "Value: " + viewModel.NumericValue.ToString("F0"),
            Font = new System.Drawing.Font("Segoe UI", 10f)
        };

        // Update label when the ViewModel changes.
        viewModel.PropertyChanged += (s, e) =>
        {
            if (e.PropertyName == "NumericValue")
            {
                valueLabel.Text = "Value: " + viewModel.NumericValue.ToString("F0");
            }
        };

        // Add controls to the form.
        this.Controls.Add(numericUpDown);
        this.Controls.Add(valueLabel);
    }

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

---

Key Points

Key Point	Details
ValueChanged Event	Fires after every valid update of the numeric value, enabling immediate reaction to user or programmatic changes.
PropertyChanged Event	Supports data binding by notifying changes to any public property, crucial for MVVM and dynamic UI updates.
Integration with Data Binding	Both events are essential when integrating with frameworks or patterns that rely on property change notifications.
Ease of Subscription	Events can be subscribed to directly in code, allowing for custom handlers that respond to control interactions.

---

Best Practices

Recommendation	Explanation
Always subscribe to ValueChanged for critical updates	Ensure that any dependent logic or UI updates are tied to the ValueChanged event to maintain consistency.
Leverage PropertyChanged for data binding	Use the PropertyChanged event when integrating with MVVM or other data-binding frameworks to synchronize control state with your ViewModel.
Unsubscribe when no longer needed	Prevent memory leaks by unsubscribing from events if the control is removed from the form or the event handlers are no longer necessary.
Test event handlers thoroughly	Validate that event subscriptions respond as expected to both user interactions and programmatic value changes.

---

Common Pitfalls

Pitfall	How to Avoid It
Forgetting to subscribe to events	Ensure that event handlers are attached in the initialization phase to catch all changes.
Handling events multiple times inadvertently	Avoid attaching multiple handlers to the same event unless intentional, as this can lead to unexpected behavior.
Overlooking thread-safety issues in event handlers	Use proper synchronization if event handlers update UI elements from non-UI threads.
Not updating bound data correctly	When using data binding, confirm that changes in the control are reflected in the ViewModel and vice versa.

---

Usage Scenarios

Scenario	Description	Example Use Case
Real-Time Data Updates	Use the ValueChanged event to update other parts of the UI in real time when the user adjusts the value.	Live dashboards, financial applications, or form validations.
Data Binding in MVVM	Implement PropertyChanged to synchronize control values with ViewModel properties in a data-binding scenario.	Enterprise applications using MVVM frameworks.
Logging and Analytics	Attach handlers to events to log value changes for auditing or analytics purposes.	Inventory management systems tracking changes to quantities.

---

Review

The Events for Integration feature provides essential hooks that allow developers to seamlessly integrate the advanced numeric up/down control into event-driven and data-bound applications. By leveraging the ValueChanged and PropertyChanged events, developers can easily monitor changes, synchronize data, and create responsive UI updates without additional overhead.

---

Summary

The Events for Integration feature of the advanced numeric up/down control is pivotal for building dynamic, data-driven applications. With straightforward event hooks for both value changes and property updates, developers can quickly integrate these events into their workflows, ensuring that their applications remain responsive and synchronized with user interactions.

---

Additional Sections

Integration Tips

Tip	Explanation
Initialize Event Handlers Early	Attach event handlers during the control initialization to ensure no changes are missed.
Combine with Data-Binding Frameworks	Leverage the PropertyChanged event to integrate smoothly with MVVM and other data-binding frameworks for automatic UI updates.
Debug Event Flow	Use logging or breakpoints within event handlers to trace the event sequence and ensure expected behavior.

Demo Application Example

Below is a complete sample demo application snippet that demonstrates the integration of the ValueChanged and PropertyChanged events:

using System;
using System.ComponentModel;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;
using SiticoneNetFrameworkUI.Helpers.Enum;

namespace EventsIntegrationDemo
{
    public class MainForm : Form
    {
        public MainForm()
        {
            this.Text = "Events Integration Demo";
            this.StartPosition = FormStartPosition.CenterScreen;
            this.Width = 500;
            this.Height = 300;

            // Create an instance of the advanced numeric up/down control.
            var numericUpDown = new SiticoneUpDown
            {
                Minimum = 0M,
                Maximum = 100M,
                Value = 40M,
                Increment = 5M,
                DecimalPlaces = 0,
                InputType = InputType.WholeNumbers,
                EnableDirectInput = true,
                Location = new System.Drawing.Point(50, 50)
            };

            // Subscribe to ValueChanged event.
            numericUpDown.ValueChanged += (s, e) =>
            {
                Console.WriteLine("ValueChanged: New value is " + numericUpDown.Value);
            };

            // Subscribe to PropertyChanged event.
            numericUpDown.PropertyChanged += (s, e) =>
            {
                if (e.PropertyName == "Value")
                {
                    Console.WriteLine("PropertyChanged: Value updated to " + numericUpDown.Value);
                }
            };

            // Create a label to show dynamic updates.
            var updateLabel = new Label
            {
                Location = new System.Drawing.Point(50, 120),
                Width = 300,
                Font = new System.Drawing.Font("Segoe UI", 10f)
            };

            // Update label via ValueChanged event.
            numericUpDown.ValueChanged += (s, e) =>
            {
                updateLabel.Text = "Current Value: " + numericUpDown.Value;
            };

            this.Controls.Add(numericUpDown);
            this.Controls.Add(updateLabel);
        }

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

This demo illustrates how to subscribe to and use the ValueChanged and PropertyChanged events to keep the UI in sync with control changes and to integrate the control effectively within an event-driven application.