Event Handling

This feature provides an event-driven architecture that notifies developers of key state and user interactions within the control.

Overview

The Event Handling feature of the SiticoneSplitContainer control is designed to allow developers to subscribe to various events related to system theme changes, splitter movements, panel visibility, and drag & drop actions. This extensive event framework enables dynamic responses to user interactions, making it easier to integrate and customize behavior in .NET WinForms applications.

---

Key Points

Aspect	Description
Event-Driven Architecture	The control raises events for critical interactions such as theme changes, splitter snapping, and panel reordering.
Granular Event Coverage	Specific events include changes to system themes, splitter movement via keyboard or mouse, context menu activation, and panel visibility adjustments.
Customizability	Developers can attach custom event handlers to respond to these events, enhancing control integration and user experience.

---

Best Practices

Recommendation	Details
Attach Handlers Early	Subscribe to events during control initialization to ensure all interactions are captured from the start.
Use Meaningful Event Names	Leverage descriptive event names like SystemThemeChanged or PanelVisibilityChanged to clarify handler purpose.
Unsubscribe When Not Needed	Ensure to unsubscribe event handlers on control disposal to avoid memory leaks, especially in dynamic UIs.
Handle Exceptions Gracefully	Within event handlers, incorporate try-catch blocks to prevent unhandled exceptions from affecting UI performance.

---

Common Pitfalls

Pitfall	Explanation	Mitigation Strategy
Missing Unsubscription	Failing to unsubscribe events can lead to memory leaks.	Always detach event handlers in the Dispose method or during control removal.
Overcomplicated Event Logic	Excessively heavy processing within an event handler can freeze the UI.	Offload intensive processing to background tasks or use async patterns.
Inconsistent Event Handling	Not handling similar events uniformly can lead to unexpected behavior.	Standardize event handling patterns across the application.

---

Usage Scenarios

Scenario	Description	Example Use Case
Dynamic Theme Adaptation	Responding to system theme changes to adjust control colors dynamically.	Changing header colors when the system switches from Light to Dark mode.
Splitter Movement Feedback	Tracking splitter movements via keyboard or mouse to update adjacent UI elements.	Updating a status bar with the current splitter position.
Panel Visibility Management	Monitoring panel visibility changes to log or adjust related controls.	Enabling/disabling related controls when a panel is collapsed or expanded.
Drag & Drop Reordering	Handling the start and end of panel reordering to persist changes or trigger animations.	Swapping panel contents when a drag-and-drop reorder is completed.

---

Code Examples

1. Attaching Event Handlers

Below is an example of how to attach event handlers for the key events in the control:

public class MyForm : Form
{
    private SiticoneSplitContainer splitContainer;

    public MyForm()
    {
        InitializeComponent();
        splitContainer = new SiticoneSplitContainer
        {
            Dock = DockStyle.Fill
        };

        // Attach event handlers
        splitContainer.SystemThemeChanged += OnSystemThemeChanged;
        splitContainer.SplitterSnapping += OnSplitterSnapping;
        splitContainer.SplitterMovedViaKeyboard += OnSplitterMovedViaKeyboard;
        splitContainer.PanelVisibilityChanged += OnPanelVisibilityChanged;
        splitContainer.PanelsSwapped += OnPanelsSwapped;
        splitContainer.OrientationChanged += OnOrientationChanged;
        splitContainer.PanelReorderStarted += OnPanelReorderStarted;
        splitContainer.PanelReorderCompleted += OnPanelReorderCompleted;

        Controls.Add(splitContainer);
    }

    private void OnSystemThemeChanged(object sender, SiticoneSplitContainer.SystemThemeChangedEventArgs e)
    {
        // Update UI based on e.NewTheme
        Console.WriteLine($"System theme changed to: {e.NewTheme}");
    }

    private void OnSplitterSnapping(object sender, SiticoneSplitContainer.SplitterSnapEventArgs e)
    {
        Console.WriteLine($"Splitter is snapping to: {e.SnapPosition}");
    }

    private void OnSplitterMovedViaKeyboard(object sender, SiticoneSplitContainer.SplitterMovedEventArgs e)
    {
        Console.WriteLine($"Splitter moved via keyboard to position: {e.NewSplitterDistance}");
    }

    private void OnPanelVisibilityChanged(object sender, SiticoneSplitContainer.PanelVisibilityChangedEventArgs e)
    {
        Console.WriteLine($"Panel1 visible: {e.IsPanel1Visible}, Panel2 visible: {e.IsPanel2Visible}");
    }

    private void OnPanelsSwapped(object sender, EventArgs e)
    {
        Console.WriteLine("Panels have been swapped.");
    }

    private void OnOrientationChanged(object sender, EventArgs e)
    {
        Console.WriteLine("Orientation changed.");
    }

    private void OnPanelReorderStarted(object sender, EventArgs e)
    {
        Console.WriteLine("Panel reordering started.");
    }

    private void OnPanelReorderCompleted(object sender, EventArgs e)
    {
        Console.WriteLine("Panel reordering completed.");
    }
}

2. Dynamically Changing Behavior Based on Events

This example demonstrates how you might adjust the UI in response to a theme change event:

private void OnSystemThemeChanged(object sender, SiticoneSplitContainer.SystemThemeChangedEventArgs e)
{
    // Adjust the splitter's highlight color based on the new system theme
    if (e.NewTheme == SiticoneSplitContainer.SystemTheme.Dark)
    {
        splitContainer.SplitterHighlightColor = Color.FromArgb(0, 122, 204);
    }
    else if (e.NewTheme == SiticoneSplitContainer.SystemTheme.Light)
    {
        splitContainer.SplitterHighlightColor = Color.DodgerBlue;
    }
    else
    {
        // Custom theme handling
        splitContainer.SplitterHighlightColor = Color.Gray;
    }
    splitContainer.Invalidate();
}

---

Review

Review Aspect	Details
Integration Ease	The event model is straightforward, enabling quick subscription and custom handler logic.
Flexibility	Developers can respond to a broad range of events from user interactions to system changes.
Maintainability	Centralized event management aids in the separation of concerns and easier code maintenance.

---

Summary

The Event Handling feature in the SiticoneSplitContainer control provides a comprehensive set of events that cover system theme changes, splitter movements, and panel interactions. By subscribing to these events, developers can build dynamic, responsive user interfaces with minimal overhead, ensuring a robust and interactive application experience.

---

Additional Sections

Integration Steps

Step	Action
Step 1	Instantiate the SiticoneSplitContainer and add it to your form.
Step 2	Subscribe to relevant events early in the control lifecycle (e.g., during form initialization).
Step 3	Implement event handlers to manage UI changes and interactions based on event data.
Step 4	Test the control in different scenarios (e.g., theme change, splitter movement) to ensure expected behavior.

Additional Resources

Resource	Description	Example Link
Official .NET Docs	Detailed information on event handling in .NET WinForms.	https://docs.microsoft.com/
Code Samples Repository	Repository of sample projects using SiticoneSplitContainer for various scenarios.	(Link to repository if available)

---

By following this documentation, developers can leverage the Event Handling capabilities of the SiticoneSplitContainer control effectively, ensuring responsive, well-organized, and maintainable WinForms applications.