Events and Callbacks

Overview

The Events and Callbacks feature of the SiticoneFlowPanel control exposes several events that notify developers of important changes or actions within the control. These events include notifications for system theme changes, DPI updates, drag operations on items, and changes in the virtualization state. By subscribing to events such as SystemThemeChanged, DpiChanged, ItemDragging, and VirtualizationStateChanged, developers can implement custom behaviors and update the UI dynamically in response to user interactions or system-level changes.

---

Detailed Documentation

1. Properties, Methods, and Events

The table below summarizes the key events and callbacks provided by the control:

Property/Method/Event	Type	Description
SystemThemeChanged	Event	Triggered when the system theme changes (e.g., Light, Dark, or Custom), allowing for dynamic UI adjustments in response to theme updates.
DpiChanged	Event	Raised when a change in system DPI is detected, providing new DPI information through DpiChangedEventArgs for custom scaling logic.
ItemDragging	Event	Fired when an item within the panel is being dragged, enabling developers to provide real-time visual feedback or custom logic during drag operations.
VirtualizationStateChanged	Event	Notifies when the virtualization state of the panel changes, typically triggered when the number of child controls exceeds a specified threshold.
OnSystemThemeChanged(SystemThemeChangedEventArgs e)	Callback Method	A protected method that invokes the SystemThemeChanged event; can be overridden to customize the behavior when a theme change occurs.
OnDpiChanged(DpiChangedEventArgs e)	Callback Method	A protected method that raises the DpiChanged event; useful for integrating custom DPI scaling behavior.
OnItemDragging(ItemDragEventArgs e)	Callback Method	A protected method that triggers the ItemDragging event, allowing additional processing when an item is being dragged.
OnVirtualizationStateChanged(VirtualizationEventArgs e)	Callback Method	A protected method that fires the VirtualizationStateChanged event when the control's virtualization state is updated.

---

2. Key Points

Key Point	Details
Event-Driven Architecture	The control uses events to communicate significant state changes, allowing for responsive and dynamic UI behavior.
Customizability through Callbacks	Protected callback methods (OnSystemThemeChanged, OnDpiChanged, etc.) can be overridden to extend or modify default behaviors.
Real-Time Interaction Feedback	Events such as ItemDragging provide real-time feedback during user interactions, enhancing the interactivity of the UI.
Adaptive UI Updates	By handling SystemThemeChanged and DpiChanged, developers can ensure that the control and surrounding UI remain consistent with system settings.

---

3. Code Examples

Example 1: Handling System Theme Changes

This example shows how to subscribe to the SystemThemeChanged event and update UI elements based on the new theme.

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

namespace EventCallbackDemo
{
    public partial class MainForm : Form
    {
        private SiticoneFlowPanel flowPanel;

        public MainForm()
        {
            InitializeComponent();
            InitializeFlowPanel();
        }

        private void InitializeFlowPanel()
        {
            flowPanel = new SiticoneFlowPanel
            {
                Dock = DockStyle.Fill,
                IsTrackingTheme = true  // Enable theme tracking to trigger events
            };

            flowPanel.SystemThemeChanged += FlowPanel_SystemThemeChanged;

            // Add sample controls
            for (int i = 0; i < 3; i++)
            {
                Label label = new Label
                {
                    Text = $"Label {i + 1}",
                    Width = 120,
                    Height = 30,
                    TextAlign = System.Drawing.ContentAlignment.MiddleCenter,
                    BorderStyle = BorderStyle.FixedSingle
                };
                flowPanel.Controls.Add(label);
            }

            Controls.Add(flowPanel);
        }

        private void FlowPanel_SystemThemeChanged(object sender, SiticoneFlowPanel.SystemThemeChangedEventArgs e)
        {
            // Update UI elements or log the new theme
            MessageBox.Show($"The system theme has changed to: {e.NewTheme}");
        }
    }
}

Example 2: Responding to DPI Changes

This sample demonstrates how to subscribe to the DpiChanged event and adjust UI scaling accordingly.

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

namespace EventCallbackDemo
{
    public partial class MainForm : Form
    {
        private SiticoneFlowPanel flowPanel;

        public MainForm()
        {
            InitializeComponent();
            InitializeFlowPanel();
        }

        private void InitializeFlowPanel()
        {
            flowPanel = new SiticoneFlowPanel
            {
                Dock = DockStyle.Fill,
                EnableAutoScale = true // Enable DPI scaling
            };

            flowPanel.DpiChanged += FlowPanel_DpiChanged;

            // Add sample controls
            for (int i = 0; i < 4; i++)
            {
                Button btn = new Button
                {
                    Text = $"Button {i + 1}",
                    Width = 90,
                    Height = 35
                };
                flowPanel.Controls.Add(btn);
            }

            Controls.Add(flowPanel);
        }

        private void FlowPanel_DpiChanged(object sender, SiticoneFlowPanel.DpiChangedEventArgs e)
        {
            // Adjust any custom UI elements based on the new DPI
            MessageBox.Show($"DPI has changed to: {e.NewDpi}");
        }
    }
}

Example 3: Tracking Item Dragging

This example demonstrates subscribing to the ItemDragging event to provide custom feedback during drag operations.

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

namespace EventCallbackDemo
{
    public partial class MainForm : Form
    {
        private SiticoneFlowPanel flowPanel;

        public MainForm()
        {
            InitializeComponent();
            InitializeFlowPanel();
        }

        private void InitializeFlowPanel()
        {
            flowPanel = new SiticoneFlowPanel
            {
                Dock = DockStyle.Fill,
                EnableDragDrop = true,  // Enable drag-and-drop support
                EnableSmoothScrolling = true
            };

            flowPanel.ItemDragging += FlowPanel_ItemDragging;

            // Add sample controls
            for (int i = 0; i < 5; i++)
            {
                Button btn = new Button
                {
                    Text = $"Drag Me {i + 1}",
                    Width = 100,
                    Height = 30,
                    BackColor = System.Drawing.Color.LightBlue
                };
                flowPanel.Controls.Add(btn);
            }

            Controls.Add(flowPanel);
        }

        private void FlowPanel_ItemDragging(object sender, SiticoneFlowPanel.ItemDragEventArgs e)
        {
            // Provide visual feedback during the drag operation
            Console.WriteLine($"Dragging {e.DraggedItem.Text} at position {e.Location}");
        }
    }
}

---

4. Usage Scenarios

Scenario	Explanation
Adaptive Theme Applications	Use SystemThemeChanged to automatically update UI colors and styles when the user changes the system theme, ensuring a cohesive look.
High DPI Environments	Subscribe to DpiChanged to scale fonts and UI elements appropriately on high-resolution displays, maintaining legibility and layout integrity.
Interactive Layout Reordering	Leverage ItemDragging to provide immediate visual feedback or custom behaviors during drag-and-drop operations within the panel.
Dynamic Virtualization Updates	Handle VirtualizationStateChanged to monitor and log changes in the virtualization state when the number of controls crosses a specific threshold.

---

5. Best Practices

Best Practice	Recommendation
Centralize Event Handling	Consolidate event handling logic in a central location or helper class to keep the code organized and maintainable.
Avoid Heavy Processing in Handlers	Keep the logic inside event handlers lightweight to prevent UI freezes, especially during high-frequency events like dragging or DPI changes.
Unsubscribe When Necessary	Remove event subscriptions when controls are disposed or no longer needed to prevent memory leaks.
Override Callbacks for Custom Behavior	Consider overriding protected callback methods (e.g., OnSystemThemeChanged) if you need to extend or modify default behaviors comprehensively.

---

6. Common Pitfalls

Pitfall	Explanation	How to Avoid
Blocking UI Thread in Event Handlers	Performing long-running tasks within event handlers (e.g., heavy calculations during DPI scaling) can block the UI thread, leading to unresponsive behavior.	Offload heavy processing to background threads or use asynchronous patterns where possible.
Memory Leaks from Unsubscribed Events	Failing to unsubscribe from events when a control is disposed can lead to memory leaks, as the control remains referenced in event handlers.	Ensure proper unsubscription in the control’s Dispose method or during cleanup routines.
Overcomplicating Event Logic	Complex logic within event handlers can become hard to maintain and debug, particularly if multiple events interact with each other.	Keep event handler logic simple and modular, delegating complex operations to separate methods or services.

---

7. Review

Aspect	Summary
Event-Driven Updates	The control leverages an event-driven architecture to notify developers of key state changes, enabling responsive and adaptive UIs.
Real-Time Feedback	Events such as ItemDragging provide immediate feedback during user interactions, enhancing the overall user experience.
Customizable Callbacks	Protected callback methods allow developers to override and extend default behaviors for a tailored integration experience.
Comprehensive Integration	By handling events related to theme, DPI, and interaction, the control ensures that both appearance and behavior remain in sync with system changes.

---

8. Summary

The Events and Callbacks feature of the SiticoneFlowPanel control empowers developers to implement custom logic in response to critical events such as theme changes, DPI updates, item dragging, and virtualization state transitions. By subscribing to and optionally overriding these events and callbacks, developers can create highly responsive and adaptive UIs that react seamlessly to both user interactions and system-level changes.

---

9. Additional Resources

Resource	Description
Code Samples	Review the provided examples to understand how to subscribe to and handle each event effectively.
.NET Event Handling Documentation	Consult the official .NET documentation on event handling to deepen your understanding of event-driven programming.
UI/UX Design Guidelines	Refer to modern UI/UX best practices to integrate event-driven updates into a cohesive user experience.

This comprehensive documentation serves as an in-depth guide for developers aiming to fully leverage the Events and Callbacks feature of the SiticoneFlowPanel control in their .NET WinForms applications.