Events and Callbacks

This feature allows the control to communicate state changes and interactions via events, enabling developers to respond programmatically to theme updates and badge value changes.

Overview

The Events and Callbacks feature exposes key events from the SiticoneImageButton control, such as the SystemThemeChanged and BadgeValueChanged events. These events enable your application to react dynamically to changes in system theme preferences and badge value updates, facilitating custom styling and logic that keeps your UI responsive and in sync with user interactions.

---

Key Points

Aspect	Description
SystemThemeChanged Event	Fires when the system theme changes, providing a SystemThemeChangedEventArgs object that details the new theme; this event is triggered when theme tracking is enabled.
BadgeValueChanged Event	Fires whenever the badge value is updated, delivering a BadgeValueChangedEventArgs object that contains the new badge value, allowing dynamic responses to badge updates.

---

Best Practices

Best Practice Area	Recommendation
Event Subscription	Subscribe to the SystemThemeChanged and BadgeValueChanged events early in the application lifecycle to ensure that all theme and badge updates are handled appropriately.
Lightweight Handlers	Keep event handlers simple and efficient to prevent UI slowdowns, especially if the event is fired frequently (e.g., during rapid badge updates).
Unsubscription Management	Always unsubscribe from events when they are no longer needed (for example, when disposing of a form) to avoid memory leaks and unintended behavior.

---

Common Pitfalls

Pitfall Area	Description	Mitigation Strategy
Overly Complex Handlers	Complex or long-running logic within event handlers may block the UI thread, causing performance issues.	Offload heavy processing to background tasks or keep event logic minimal and efficient.
Neglecting Unsubscriptions	Failing to unsubscribe from events can lead to memory leaks or unexpected behavior when the control is disposed and recreated multiple times.	Ensure that event handlers are properly unsubscribed when controls are disposed or no longer needed.
Ignoring Event Arguments	Not utilizing the event argument objects (SystemThemeChangedEventArgs, BadgeValueChangedEventArgs) may result in missed opportunities for tailored UI updates.	Use the provided event data to implement context-sensitive logic that enhances the user experience.

---

Usage Scenarios

Scenario	Explanation	Recommended Settings
Dynamic Theme Adjustments	Use the SystemThemeChanged event to update control styling or trigger animations when the system theme changes (e.g., switching between dark and light modes).	Subscribe to the SystemThemeChanged event and update properties like BorderColor or BackgroundFillColor accordingly.
Real-Time Badge Updates	Use the BadgeValueChanged event to respond to changes in notification counts or other badge-related data, updating other UI elements or triggering animations.	Subscribe to the BadgeValueChanged event to synchronize badge displays or log changes for analytics.
Centralized Event Handling	In complex applications with multiple theme-aware or badge-enabled controls, centralize event handling to manage updates consistently across the UI.	Create a common event handler method to propagate changes across different controls when an event is fired.

---

Code Examples

Example 1: Handling Theme Changes with SystemThemeChanged

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

public class ThemeEventForm : Form
{
    private SiticoneImageButton imageButton;

    public ThemeEventForm()
    {
        // Initialize the image button with theme integration enabled
        imageButton = new SiticoneImageButton
        {
            Size = new Size(100, 100),
            Location = new Point(50, 50),
            TrackSystemTheme = true
        };

        // Subscribe to the SystemThemeChanged event
        imageButton.SystemThemeChanged += OnSystemThemeChanged;

        Controls.Add(imageButton);
    }

    // Event handler for system theme changes
    private void OnSystemThemeChanged(object sender, SystemThemeChangedEventArgs e)
    {
        // Update the control's border color based on the new theme
        imageButton.BorderColor = (e.NewTheme == SystemTheme.Dark) ? Color.White : Color.Black;

        // Optionally, perform additional custom actions
        Console.WriteLine("Theme changed to: " + e.NewTheme);
    }

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

Example 2: Responding to Badge Value Changes with BadgeValueChanged

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

public class BadgeEventForm : Form
{
    private SiticoneImageButton imageButton;

    public BadgeEventForm()
    {
        // Initialize the image button with an initial badge value
        imageButton = new SiticoneImageButton
        {
            Size = new Size(100, 100),
            Location = new Point(50, 50),
            BadgeValue = 3
        };

        // Subscribe to the BadgeValueChanged event
        imageButton.BadgeValueChanged += OnBadgeValueChanged;

        Controls.Add(imageButton);

        // Simulate a badge update after 3 seconds
        Timer timer = new Timer { Interval = 3000 };
        timer.Tick += (s, e) =>
        {
            imageButton.BadgeValue = 10;
            timer.Stop();
        };
        timer.Start();
    }

    // Event handler for badge value changes
    private void OnBadgeValueChanged(object sender, BadgeValueChangedEventArgs e)
    {
        // Log the new badge value or update other UI elements accordingly
        MessageBox.Show("Badge value updated to: " + e.NewValue);
    }

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

---

Integration Demos

Demo Type	Description	Code Reference
Theme Change Demo	Demonstrates how to subscribe to and handle the SystemThemeChanged event to adjust the control's appearance dynamically.	Example 1 above
Badge Update Demo	Shows how to respond to changes in the badge value by updating UI elements or triggering notifications.	Example 2 above

---

Additional Considerations

Consideration	Details
Event Handler Efficiency	Optimize your event handlers to perform minimal processing on the UI thread; offload intensive tasks to background threads where possible.
Consistent Unsubscription	In forms or controls that may be created and destroyed repeatedly, ensure that event handlers are unsubscribed to avoid memory leaks or orphaned callbacks.
Centralized Event Management	For large-scale applications, consider implementing a centralized event management system that propagates changes across multiple controls uniformly.

---

Review

The Events and Callbacks feature of the SiticoneImageButton control empowers developers to build dynamic and responsive UIs by providing hooks for significant state changes, such as system theme updates and badge value modifications. These events enable tailored responses—ranging from aesthetic adjustments to functional updates—ensuring that your application remains both interactive and visually consistent.

---

Summary

The Events and Callbacks feature in the SiticoneImageButton control facilitates dynamic, event-driven programming by exposing events like SystemThemeChanged and BadgeValueChanged. By subscribing to these events, developers can implement custom logic to handle theme transitions and badge updates, thereby ensuring that the control behaves responsively and in harmony with the overall application design. This feature is critical for creating adaptable, modern WinForms applications that respond to user and system-level changes.

---

Key Points Recap

Recap Point	Details
Event-Driven Architecture	The control uses events to communicate state changes, allowing external code to react dynamically to system theme and badge value updates.
Customizable Responses	Developers can implement custom logic in event handlers to update the UI or trigger additional actions based on theme changes or badge updates.
Performance and Efficiency	Keep event handlers lightweight and manage subscriptions properly to ensure that dynamic event handling does not negatively impact the application's performance.

---

Usage Scenarios Recap

Scenario	Application Example
Adaptive UI Updates	Use SystemThemeChanged to adjust UI elements such as border colors or backgrounds dynamically when the system theme changes.
Notification Handling	Use BadgeValueChanged to trigger notifications, update other parts of the UI, or log changes when the badge value is modified during runtime.
Centralized Event Coordination	Implement centralized event handlers to propagate changes uniformly across multiple controls that rely on theme and badge updates.

---

Conclusion

The Events and Callbacks feature is integral to building dynamic, responsive WinForms applications with the SiticoneImageButton control. By exposing events like SystemThemeChanged and BadgeValueChanged, the control allows developers to respond effectively to key state changes, ensuring that UI updates and notifications are handled in real time. This comprehensive guide—complete with best practices, code examples, and usage scenarios—serves as a valuable resource for integrating and optimizing event-driven functionality within your application.

This documentation should help you leverage the event-driven capabilities provided by the control’s code to create an adaptive and engaging user experience.