Events and Callbacks

Overview

This section covers the events and callbacks exposed by the control. These events enable developers to hook into key moments such as theme changes, text updates, validation results, and property changes so that they can execute custom logic or update other parts of the user interface accordingly.

---

Key Points

Aspect	Description
State Notifications	Events notify when key state changes occur, such as theme updates and text modifications.
Validation Callbacks	The control provides events to signal when input validation has been performed, allowing the application to respond to errors or success.
Property Change Updates	Implements the INotifyPropertyChanged event to propagate changes in control properties, ensuring external components can react accordingly.
Custom Interaction Hooks	Enables developers to integrate custom logic by subscribing to callbacks for user interactions like text updates.

---

Best Practices

Practice Area	Recommendation
Subscribe Early	Subscribe to events (e.g., SystemThemeChanged, TextUpdated) during initialization to ensure no state change is missed.
Unsubscribe When Appropriate	Unsubscribe from events when the control is disposed or no longer needed to avoid memory leaks.
Centralized Event Handling	Use centralized methods or event aggregator patterns if multiple events require similar handling logic to keep the code organized.
Minimal Event Processing	Keep event handlers efficient; perform only necessary logic to prevent blocking the UI thread during high-frequency events like text updates.

---

Common Pitfalls

Pitfall	Description
Memory Leaks	Failing to unsubscribe from events can prevent garbage collection of the control, leading to memory leaks in long-running applications.
Over-Processing Events	Performing heavy processing in event handlers (e.g., complex UI updates) may lead to performance issues, especially for high-frequency events.
Duplicate Subscriptions	Multiple subscriptions to the same event can result in duplicate processing, which might cause unintended behavior or inconsistent state updates.
Ignoring Event Order	Relying on a specific order of event firing may lead to issues if the control's internal implementation changes in the future.

---

Real Life Usage Scenarios

Scenario	Description
Dynamic Theme Adjustments	Automatically update related UI elements when the system theme changes by handling the SystemThemeChanged event.
Live Text Monitoring	Implement real-time logging or processing of user input by subscribing to the TextUpdated event.
Validation-Driven Workflows	Trigger external business logic or display user notifications when input validation fails or passes by handling the Validated event.
Data Binding Integration	Use the PropertyChanged event to ensure that changes to control properties are reflected in bound models, keeping the UI in sync with data.

---

Troubleshooting Tips

Issue	Suggested Solution
Missed State Updates	Verify that event subscriptions are set up before any changes occur and that no duplicate subscriptions are interfering with the expected behavior.
Performance Bottlenecks	Optimize event handlers to perform only essential operations; consider offloading heavy processing to background tasks if needed.
Memory Leaks	Ensure that event handlers are unsubscribed when the control is disposed; use weak event patterns if available.
Inconsistent Callback Data	Validate that the data provided in event arguments (e.g., in TextUpdatedEventArgs or SystemThemeChangedEventArgs) is correctly handled and updated.

---

Property and Event Reference

Below is a reference table of key events and callbacks exposed by the control:

Property/Method/Event	Type/Return	Description
TextUpdated	event EventHandler <TextUpdatedEventArgs>	Raised when the text content of the control changes, providing both previous and current text values.
Validated	event ValidationEventHandler	Raised after input validation has been performed, allowing custom logic based on whether the text is valid.
SystemThemeChanged	event EventHandler <SystemThemeChangedEventArgs>	Notifies subscribers when the system theme changes, providing the updated theme information.
PropertyChanged	event PropertyChangedEventHandler	Part of the INotifyPropertyChanged implementation; notifies subscribers when a property value changes.
Undo()/Redo() Methods	void	Methods that trigger undo or redo operations; while not events, they are callable callbacks affecting the control's state.

---

Code Examples

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

Example 1: Handling Text Updates

This example shows how to subscribe to the TextUpdated event and log the changes.

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

public class TextUpdateForm : Form
{
    public TextUpdateForm()
    {
        var customTextBox = new SiticoneTextBox
        {
            Text = "Initial text",
            Location = new System.Drawing.Point(20, 20),
            Size = new System.Drawing.Size(300, 40)
        };

        // Subscribe to the TextUpdated event
        customTextBox.TextUpdated += (sender, e) =>
        {
            Console.WriteLine($"Text changed from '{e.PreviousText}' to '{e.CurrentText}'");
        };

        Controls.Add(customTextBox);
        Text = "Text Updated Event Demo";
        Size = new System.Drawing.Size(360, 120);
    }

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

---

Example 2: Custom Validation Handling

This example demonstrates subscribing to the Validated event to react when input validation is performed.

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

public class ValidationEventForm : Form
{
    public ValidationEventForm()
    {
        var customTextBox = new SiticoneTextBox
        {
            Text = "",
            Location = new System.Drawing.Point(20, 20),
            Size = new System.Drawing.Size(300, 40)
        };

        // Define a simple validation function
        customTextBox.ValidationFunction = text => !string.IsNullOrWhiteSpace(text);

        // Subscribe to the Validated event
        customTextBox.Validated += (sender, e) =>
        {
            if (!customTextBox.IsValid)
            {
                MessageBox.Show("Input is invalid.", "Validation Error", MessageBoxButtons.OK, MessageBoxIcon.Warning);
            }
        };

        Controls.Add(customTextBox);
        Text = "Validation Event Demo";
        Size = new System.Drawing.Size(360, 120);
    }

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

---

Example 3: Responding to System Theme Changes

This example illustrates how to subscribe to the SystemThemeChanged event and perform custom logic when the system theme is updated.

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

public class ThemeChangedForm : Form
{
    public ThemeChangedForm()
    {
        var customTextBox = new SiticoneTextBox
        {
            TrackSystemTheme = true,
            Location = new System.Drawing.Point(20, 20),
            Size = new System.Drawing.Size(300, 40)
        };

        // Subscribe to the SystemThemeChanged event
        customTextBox.SystemThemeChanged += (sender, e) =>
        {
            MessageBox.Show($"System theme has changed to: {e.Theme}", "Theme Update", MessageBoxButtons.OK, MessageBoxIcon.Information);
        };

        Controls.Add(customTextBox);
        Text = "System Theme Changed Demo";
        Size = new System.Drawing.Size(360, 120);
    }

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

---

Frequently Asked Questions

Question	Answer
How do I subscribe to control events?	Subscribe to events like TextUpdated, Validated, or SystemThemeChanged by attaching event handlers (using the += syntax) in your form or control initialization code.
What is the purpose of the PropertyChanged event?	It notifies subscribers when a property value changes, which is useful for data binding and ensuring that external components remain synchronized with the control.
How can I ensure that my event handlers do not impact performance?	Keep your event handlers lightweight by performing minimal processing, and consider offloading heavy tasks to background threads if necessary.
How do I handle multiple events in a single handler?	Use a centralized method to process event arguments and route the logic accordingly, or use lambda expressions to keep the code organized.
How can I prevent memory leaks related to event subscriptions?	Unsubscribe from events when the control is disposed or no longer needed, for example, in the FormClosing event or Dispose method of your component.

---

Integration Checklist

Step	Verification
Event Subscription	Confirm that key events (TextUpdated, Validated, SystemThemeChanged, PropertyChanged) are subscribed early in the control's lifecycle.
Unsubscription Practices	Verify that event handlers are unsubscribed appropriately when the control is disposed to prevent memory leaks.
Handler Efficiency	Ensure that event handlers perform only necessary operations and do not block the UI thread.
Testing Callback Order	Test the order and frequency of event firing to ensure that the application logic responds as expected.
Custom Event Logic	Validate that any custom logic implemented in event handlers does not conflict with the control’s internal behavior.
Cross-Component Integration	Confirm that event notifications integrate smoothly with data binding or external controllers in your application.

---

Review

Review Aspect	Details
Event Responsiveness	The control provides timely notifications for key interactions, enabling developers to react promptly to state changes and user input.
Ease of Event Integration	With clearly named events and consistent event arguments, integrating custom logic via event handlers is straightforward.
Memory and Performance	Proper event handling and unsubscription practices ensure that the control remains performant without memory leaks.
Flexibility in Customization	The variety of events (state changes, validation, property changes) offers developers multiple hooks to tailor the control's behavior to their needs.

---

Summary

Events and Callbacks in the control facilitate real-time notification of changes and user interactions. By subscribing to events like TextUpdated, Validated, SystemThemeChanged, and PropertyChanged, developers can seamlessly integrate custom logic, provide user feedback, and maintain data synchronization across the application.