# Drag and Drop Panel Reordering

## Overview

The Drag & Drop Panel Reordering feature in the SiticoneSplitContainer control allows developers to enable intuitive panel swapping through mouse interactions. When activated, users can initiate a drag action on either panel, and upon completion, the panels' content and associated properties are swapped. The control exposes events such as `PanelReorderStarted` and `PanelReorderCompleted` to facilitate custom behaviors during the reordering process, providing a flexible way to update the UI dynamically.

***

### Key Points

| Aspect                  | Description                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Drag Initiation         | Users can start dragging a panel by clicking and holding within the panel area, which then triggers the reordering process. |
| Reordering Events       | The events `PanelReorderStarted` and `PanelReorderCompleted` notify developers when a panel drag begins and ends.           |
| Content & Property Swap | The control swaps not only the panel contents but also related properties such as minimum sizes and header texts.           |
| Optional Enablement     | The reordering functionality is optional and can be toggled using the `EnablePanelReordering` property.                     |

***

### Best Practices

| Recommendation                   | Details                                                                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Enable Only When Necessary       | Activate `EnablePanelReordering` only in scenarios where panel order changes are expected, to avoid unintended drags.                      |
| Provide Visual Feedback          | Use visual cues (such as a dashed border) during the drag operation to indicate that the panel is being reordered.                         |
| Handle Reorder Events Gracefully | Attach handlers to `PanelReorderStarted` and `PanelReorderCompleted` to manage any state changes or additional UI updates.                 |
| Validate Drag Operations         | Ensure that dragging operations do not interfere with other control interactions by verifying the drag start point and movement threshold. |

***

### Common Pitfalls

| Pitfall                  | Explanation                                                                                                    | Mitigation Strategy                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Unintentional Reordering | If reordering is enabled in contexts where panels should remain static, accidental swaps may confuse the user. | Disable reordering by default and enable it only when needed using `EnablePanelReordering`.          |
| Overlapping Drag Regions | If the drag start area is not clearly defined, users may trigger reordering unintentionally.                   | Define clear drag boundaries and consider using visual indicators to show when reordering is active. |
| Insufficient Feedback    | Without proper visual feedback, users might not realize that a drag operation is in progress.                  | Provide immediate visual feedback (e.g., drawing a dashed rectangle) when a drag is detected.        |

***

### Usage Scenarios

| Scenario                     | Description                                                                                                                   | Example Use Case                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Reordering Navigation Panels | Users can drag panels to rearrange their order, customizing the layout to prioritize frequently accessed content.             | In a dashboard, a user drags the navigation panel to swap its position with a content panel.                   |
| Dynamic Content Management   | Applications where the order of panels is significant (e.g., in data dashboards or design tools) can benefit from reordering. | In a design application, swapping panels may reorganize toolsets and workspace views based on user preference. |
| Custom Layout Adjustments    | Enable administrators to rearrange panels at runtime, tailoring the UI to match different workflows or user roles.            | An enterprise app that allows different departments to have custom panel arrangements based on their workflow. |

***

### Code Examples

#### 1. Enabling Drag & Drop Reordering

The following example shows how to enable panel reordering within the control:

```csharp
public class DragDropReorderForm : Form
{
    private SiticoneSplitContainer splitContainer;

    public DragDropReorderForm()
    {
        InitializeComponent();
        splitContainer = new SiticoneSplitContainer
        {
            Dock = DockStyle.Fill,
            // Enable panel reordering via drag and drop
            EnablePanelReordering = true
        };

        // Optionally, subscribe to events for custom behavior
        splitContainer.PanelReorderStarted += OnPanelReorderStarted;
        splitContainer.PanelReorderCompleted += OnPanelReorderCompleted;

        this.Controls.Add(splitContainer);
    }

    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. Visual Feedback During Drag Operation

This example demonstrates how you might provide visual feedback during a drag operation by handling panel repaint events (the control itself draws a dashed border when dragging is in progress):

```csharp
public class VisualFeedbackForm : Form
{
    private SiticoneSplitContainer splitContainer;

    public VisualFeedbackForm()
    {
        InitializeComponent();
        splitContainer = new SiticoneSplitContainer
        {
            Dock = DockStyle.Fill,
            EnablePanelReordering = true
        };

        // Subscribe to reordering events to update the UI as needed
        splitContainer.PanelReorderStarted += (s, e) =>
        {
            // Additional UI logic can be placed here
            Console.WriteLine("Drag initiated. Provide visual feedback if necessary.");
        };

        splitContainer.PanelReorderCompleted += (s, e) =>
        {
            Console.WriteLine("Drag completed. Refresh UI accordingly.");
        };

        this.Controls.Add(splitContainer);
    }
}
```

#### 3. Handling Edge Cases During Reordering

In this example, additional logic can be implemented in the event handlers to validate the drag operation or revert changes if necessary:

```csharp
public class SafeReorderingForm : Form
{
    private SiticoneSplitContainer splitContainer;

    public SafeReorderingForm()
    {
        InitializeComponent();
        splitContainer = new SiticoneSplitContainer
        {
            Dock = DockStyle.Fill,
            EnablePanelReordering = true
        };

        splitContainer.PanelReorderCompleted += (sender, e) =>
        {
            // Validate that the new order is acceptable.
            // If not, revert to the previous order or display a warning message.
            Console.WriteLine("Reordering completed. Validate new order if necessary.");
        };

        this.Controls.Add(splitContainer);
    }
}
```

***

### Review

| Aspect           | Details                                                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integration Ease | Enabling drag and drop panel reordering is as simple as setting a property, with events provided to allow for custom handling of the reordering process.        |
| User Experience  | The feature enhances interactivity, allowing users to intuitively rearrange panels, thus tailoring the UI to their preferences.                                 |
| Flexibility      | Through the provided events and properties, developers have granular control over the reordering process, enabling integration with complex UI logic if needed. |

***

### Summary

The Drag & Drop Panel Reordering feature of the SiticoneSplitContainer control provides an intuitive way for users to dynamically rearrange panels through simple drag and drop interactions. With built-in events to signal the start and completion of reordering, developers can easily integrate custom behaviors and visual feedback into their applications, thereby creating a more interactive and user-adaptive interface.

***

### Integration Steps

| Step   | Action                                                                                                                                                    |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Step 1 | Instantiate the SiticoneSplitContainer and set the `Dock` property appropriately in your form.                                                            |
| Step 2 | Enable panel reordering by setting `EnablePanelReordering` to true.                                                                                       |
| Step 3 | Optionally subscribe to `PanelReorderStarted` and `PanelReorderCompleted` events to handle custom behavior during the drag operation.                     |
| Step 4 | Provide visual feedback (e.g., using custom drawing logic or built-in cues) to clearly indicate that a drag operation is in progress.                     |
| Step 5 | Test the reordering feature across various scenarios to ensure that panel swapping works as expected without interfering with other control interactions. |

***

### Additional Resources

| Resource                         | Description                                                                       | Example Link                                                                |
| -------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| .NET Drag and Drop Documentation | Detailed information on implementing drag and drop in .NET WinForms applications. | <https://docs.microsoft.com/dotnet/desktop/winforms/advanced/drag-and-drop> |
| WinForms UI Best Practices       | Articles and tutorials on best practices for interactive UI design in WinForms.   | (Link to a recommended tutorial or blog post)                               |

***

By following this comprehensive documentation and utilizing the provided code examples, developers can effectively integrate drag and drop panel reordering into their WinForms applications using the SiticoneSplitContainer control. This feature enhances user interaction and enables dynamic, customizable layouts tailored to user needs.