Events and Callbacks

This feature provides developers with hooks into the control's lifecycle by exposing events and callbacks to respond to dynamic content updates, drag operations, and context menu actions.

Overview

The Events and Callbacks feature of the SiticoneContainer control enables developers to intercept key moments during user interactions and control state changes. Events such as ContentLoaded, DragStarted, DragCompleted, and ContextMenuOpened allow custom logic to be executed in response to dynamic content loading, drag-and-drop interactions, and context menu activations. This mechanism enhances integration flexibility and allows the application to respond dynamically to user actions.

---

Key Points

Event/Callback	Description	When Triggered
ContentLoaded	Raised when dynamic content is successfully loaded into the control via the ContentGenerator.	After calling LoadContent with dynamic content data.
DragStarted	Raised when a drag operation is initiated on the control.	When the user starts dragging (mouse down with sufficient movement).
DragCompleted	Raised when the drag operation concludes and the control is repositioned.	After the drag-and-drop operation is finalized.
ContextMenuOpened	Raised when the custom context menu is displayed upon a right-click action on the control.	Right before the ContextMenuStrip is shown.

---

Best Practices

Practice	Description
Subscribe to relevant events	Attach handlers only to the events that are necessary for your application to avoid unnecessary overhead.
Ensure thread-safety	If event handlers update UI elements or shared data, ensure that they do so on the UI thread to prevent threading issues.
Validate event data	When using event callbacks, validate any data or state provided to avoid unexpected behavior.
Unsubscribe when appropriate	For long-lived controls or dynamic subscriptions, unsubscribe from events when they are no longer needed to prevent memory leaks.

---

Common Pitfalls

Pitfall	Description	Recommendation
Ignoring event subscriptions	Failing to subscribe to key events may lead to missed opportunities for dynamic updates or user feedback.	Ensure that necessary events (e.g., ContentLoaded, DragCompleted) are properly handled.
Overcomplicating event logic	Placing heavy processing or UI updates directly in event handlers may degrade performance.	Offload intensive processing to background tasks and use event handlers only for dispatching updates.
Not unsubscribing from events	Keeping event subscriptions active unnecessarily can result in memory leaks or unintended behavior during control disposal.	Unsubscribe from events when the control is disposed or no longer in use.

---

Usage Scenarios

Scenario	Description	Example Use Case
Dynamic Content Updates	Reacting to new content loaded into the control by updating other UI elements or logging the update.	Use the ContentLoaded event to refresh a status bar or log activity after dynamic content is loaded.
Drag-and-Drop Handling	Adjusting application state or rearranging layouts in response to control repositioning during a drag operation.	Use the DragStarted and DragCompleted events to update a dashboard layout when panels are repositioned.
Context Menu Customization	Altering menu items or enabling/disabling options dynamically before the context menu is shown.	Use the ContextMenuOpened event to modify menu items based on the control's current state.

---

Code Examples

Example 1: Handling Dynamic Content Loaded Event

This example shows how to subscribe to the ContentLoaded event to perform additional actions once new content is loaded.

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

public class ContentEventForm : Form
{
    public ContentEventForm()
    {
        SiticoneContainer container = new SiticoneContainer
        {
            Size = new Size(300, 200),
            Location = new Point(20, 20),
            EnableDynamicContent = true,
            DataSource = "Dynamic content loaded!",
            ContentGenerator = data =>
            {
                Label label = new Label
                {
                    Dock = DockStyle.Fill,
                    TextAlign = ContentAlignment.MiddleCenter,
                    Font = new Font("Segoe UI", 12, FontStyle.Regular),
                    Text = data.ToString()
                };
                return label;
            }
        };

        container.ContentLoaded += (s, e) =>
        {
            MessageBox.Show("Dynamic content has been loaded.");
        };

        container.LoadContent(container.DataSource);
        this.Controls.Add(container);
    }

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

Example 2: Implementing Drag Events

This example demonstrates subscribing to DragStarted and DragCompleted events to log the start and end of a drag operation.

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

public class DragEventForm : Form
{
    public DragEventForm()
    {
        SiticoneContainer draggableContainer = new SiticoneContainer
        {
            Size = new Size(250, 150),
            Location = new Point(20, 20),
            EnableDragging = true
        };

        draggableContainer.DragStarted += (s, e) =>
        {
            Console.WriteLine("Drag operation started.");
        };

        draggableContainer.DragCompleted += (s, e) =>
        {
            Console.WriteLine($"Drag operation completed. New location: {draggableContainer.Location}");
        };

        this.Controls.Add(draggableContainer);
    }

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

Example 3: Customizing the Context Menu with Callbacks

This example shows how to dynamically modify the context menu using the ContextMenuOpened event before the menu is displayed.

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

public class ContextMenuEventForm : Form
{
    private ContextMenuStrip dynamicContextMenu;

    public ContextMenuEventForm()
    {
        dynamicContextMenu = new ContextMenuStrip();

        SiticoneContainer container = new SiticoneContainer
        {
            Size = new Size(300, 200),
            Location = new Point(20, 20),
            EnableContextMenu = true,
            ContextMenu = dynamicContextMenu
        };

        container.ContextMenuOpened += (s, e) =>
        {
            // Clear any existing menu items
            dynamicContextMenu.Items.Clear();
            
            // Dynamically add menu items based on a condition
            if (DateTime.Now.Second % 2 == 0)
            {
                dynamicContextMenu.Items.Add("Even Option", null, (sender, args) => MessageBox.Show("Even option selected."));
            }
            else
            {
                dynamicContextMenu.Items.Add("Odd Option", null, (sender, args) => MessageBox.Show("Odd option selected."));
            }
            // Add a common option regardless of state
            dynamicContextMenu.Items.Add("Common Option", null, (sender, args) => MessageBox.Show("Common option selected."));
        };

        this.Controls.Add(container);
    }

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

---

Review

Aspect	Notes
Responsiveness	Events allow the application to react promptly to user interactions and dynamic state changes.
Customization	Developers can tailor the control's behavior by inserting custom logic in event handlers for varied application needs.
Ease of Integration	Exposed events such as ContentLoaded, DragStarted, DragCompleted, and ContextMenuOpened are straightforward to subscribe to and use.

---

Summary

The Events and Callbacks feature of the SiticoneContainer control provides essential hooks for developers to integrate custom logic into various stages of the control’s lifecycle. By leveraging events such as ContentLoaded, DragStarted, DragCompleted, and ContextMenuOpened, developers can create dynamic, responsive, and context-sensitive applications that react to user actions and state changes effectively.

---

Additional Tips

Tip	Explanation
Use minimal logic in event handlers	Keep event handler code concise to ensure that the UI remains responsive, offloading heavy tasks to background threads if necessary.
Document event behaviors	Clearly document any custom event handling logic to facilitate future maintenance and ensure consistent behavior across updates.
Test across different user scenarios	Validate that events fire as expected under various conditions (e.g., rapid interactions, multiple drags) to avoid unexpected behaviors.

This comprehensive documentation should help developers effectively integrate and customize the Events and Callbacks feature of the SiticoneContainer control in their .NET WinForms applications.