Events and Callbacks

This feature enables developers to react to changes in the control’s state by subscribing to various events, which notify them when important actions occur—such as text updates, validation, etc.

Overview

The Events feature in the SiticonePhoneNumberBox control exposes several front‑facing events that inform developers of state changes and user interactions. These events include notifications when the text is updated, when input is validated, when the validation state changes, and when the system theme is altered.

Event / Property	Type / Delegate	Description
TextUpdated	TextUpdatedEventHandler	Occurs when the text in the control changes, providing both the old and new text values to allow for reactive processing or logging.
Validated	ValidationEventHandler	Raised after the control’s input is validated, passing information about whether the input is valid and any associated error message.
ValidationStateChanged	EventHandler	Notifies subscribers when the internal validation state changes, useful for updating UI elements based on input validity.
SystemThemeChanged	EventHandler	Fires when the system theme (light or dark) changes, enabling the control and associated UI elements to update their appearance accordingly.
PropertyChanged	PropertyChangedEventHandler	Part of the INotifyPropertyChanged implementation; notifies subscribers when a public property changes, supporting data binding scenarios.

Feature Description: These events allow developers to hook into the control’s lifecycle, providing a mechanism to update other UI elements, perform validations, or log changes in response to user interaction or system updates.

---

Key Points

Aspect	Detail
Real-Time Feedback	Events such as TextUpdated and Validated deliver immediate feedback on user input, allowing dynamic UI updates and validations as text changes.
State Synchronization	The PropertyChanged and ValidationStateChanged events ensure that bound data or dependent UI components are updated when control properties change.
Adaptive UI	The SystemThemeChanged event facilitates an adaptive UI by enabling changes in control appearance to match system theme updates in real time.

---

Best Practices

Practice	Explanation
Subscribe to Events Early	Attach event handlers (e.g., for TextUpdated and Validated) during control initialization to ensure that changes are captured from the start.
Use Events for UI Synchronization	Leverage events like ValidationStateChanged and PropertyChanged to automatically update related UI elements, such as error messages or visual cues, when input changes.
Clean Up Event Handlers	Unsubscribe from events when the control is disposed to avoid memory leaks or unintended callbacks.
Log or Monitor Critical Events	Consider logging information from events like TextUpdated and SystemThemeChanged during development to debug and fine‑tune control behavior.

---

Common Pitfalls

Pitfall	How to Avoid
Forgetting to Unsubscribe from Events	Ensure that event handlers are removed (especially in dynamic forms or custom controls) to prevent memory leaks and unexpected behavior.
Overprocessing in Event Handlers	Keep event handler logic lightweight to avoid UI freezes or performance bottlenecks, particularly for events that fire frequently (e.g., TextUpdated).
Ignoring Event Order or Timing	Understand that some events (such as TextUpdated and PropertyChanged) may fire in rapid succession; avoid assuming a fixed order without proper testing.
Not Handling Theme Changes Appropriately	When using SystemThemeChanged, update all dependent visual properties to maintain a consistent appearance, instead of only partially updating the UI.

---

Usage Scenarios

Scenario	Example Use Case
Live Data Validation	Subscribe to the TextUpdated and Validated events to perform real‑time input validation, updating error messages or border colors based on input.
UI Synchronization with External Components	Use PropertyChanged or ValidationStateChanged to update other controls (like labels or progress bars) when the phone number input changes.
Adaptive Theme Updates	Handle the SystemThemeChanged event to automatically adjust the appearance of the control and other UI elements when the system theme changes.
Debugging and Logging	Attach to the TextUpdated event during development to log user input changes and diagnose issues with input formatting or validation.

---

Code Examples

Example 1: Subscribing to TextUpdated This sample demonstrates how to subscribe to the TextUpdated event to log changes in the control’s text.

// Instantiate the control
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Subscribe to the TextUpdated event
phoneNumberBox.TextUpdated += (sender, args) =>
{
    // Log the previous and current text values
    Console.WriteLine($"Text changed from '{args.OldText}' to '{args.NewText}'.");
};

// Add the control to the form
phoneNumberBox.Location = new Point(20, 20);
phoneNumberBox.Size = new Size(250, 40);
this.Controls.Add(phoneNumberBox);

Example 2: Handling Validation Results This example shows how to subscribe to the Validated event to provide user feedback based on the input’s validity.

// Configure the control's validation function
phoneNumberBox.ValidationFunction = (input) =>
{
    // Simple validation: valid if input contains exactly 10 digits
    string digits = new string(input.Where(char.IsDigit).ToArray());
    return digits.Length == 10;
};

phoneNumberBox.ValidationErrorMessage = "Please enter a valid 10-digit phone number.";

// Subscribe to the Validated event
phoneNumberBox.Validated += (sender, args) =>
{
    if (!args.IsValid)
    {
        // Display the error message (for example, in a label)
        errorLabel.Text = args.ErrorMessage;
    }
    else
    {
        errorLabel.Text = "";
    }
};

Example 3: Reacting to System Theme Changes This sample demonstrates subscribing to the SystemThemeChanged event to update the UI when the system theme changes.

// Enable system theme tracking
phoneNumberBox.TrackSystemTheme = true;

// Subscribe to the SystemThemeChanged event
phoneNumberBox.SystemThemeChanged += (sender, e) =>
{
    // Update the form's background color based on the current theme
    if (phoneNumberBox.CurrentSystemTheme == SystemTheme.Dark)
    {
        this.BackColor = Color.FromArgb(30, 30, 30);
    }
    else
    {
        this.BackColor = Color.White;
    }
};

---

Review

Aspect	Review Comment
Reactive and Dynamic	The events provide a responsive way to handle real‑time changes, ensuring that both data and UI remain synchronized.
Broad Coverage	With events covering text updates, validation results, and system theme changes, developers have the tools needed to build adaptive interfaces.
Simplicity in Integration	The straightforward event signatures and code examples facilitate quick integration without extensive boilerplate code.

---

Summary

The Events feature of the SiticonePhoneNumberBox control delivers critical notifications for text changes, validation outcomes, and system theme updates. By subscribing to events such as TextUpdated, Validated, and SystemThemeChanged, developers can create dynamic, responsive user interfaces that react appropriately to user input and system state changes. This event-driven model not only simplifies synchronization with other UI elements but also enhances the overall user experience through timely feedback.

---

Additional Notes

Note Type	Detail
Extensibility	Additional custom events or extended event arguments can be introduced if further granular control over state changes is required.
Integration Tips	Consider combining event handlers with data binding or command patterns to streamline UI updates in larger applications.
Debugging	Utilize event logging during development to track the flow of events (e.g., TextUpdated and Validated) and ensure that the UI responds as expected.