> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/buttons-and-elements/siticone-imagebutton/events-and-callbacks.md). # Events and Callbacks ## 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 ```csharp 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 ```csharp 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.