Events and Callback

Events and Callback provide a mechanism for developers to receive notifications when specific actions occur within the panel, allowing for responsive and dynamic UI behavior.

Overview

The Events and Callback feature of the SiticoneAdvancedPanel control enables developers to hook into key moments of the control's lifecycle. These events notify when the system theme changes, the ripple effect starts, the visual style is modified, or when the control receives keyboard focus. By handling these events, you can implement custom behaviors and seamlessly integrate the panel into your application's interactive flow.

---

Event Details

Event Name	Category	Description
SystemThemeChanged	Chromatic Chronicles	Fires when the system theme changes, providing the new theme (Light, Dark, or Custom).
RippleEffectStarted	Behavioral Basics	Occurs when the ripple effect is initiated, passing the origin point of the ripple.
VisualStyleChanged	Artistic Appearance	Triggered when the visual style of the control changes, notifying which property was modified.
KeyboardFocusReceived	Key Kinetics	Fires when the control receives (or loses) keyboard focus, indicating its current focus state.

---

Code Examples

Subscribing to Events

Below is an example demonstrating how to subscribe to and handle the panel's key events:

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

namespace DemoApp
{
    public class MainForm : Form
    {
        private SiticoneAdvancedPanel advancedPanel;

        public MainForm()
        {
            // Initialize the advanced panel control
            advancedPanel = new SiticoneAdvancedPanel
            {
                Size = new Size(400, 300),
                Location = new Point(50, 50),
                BackColor = Color.White
            };

            // Subscribe to events
            advancedPanel.SystemThemeChanged += AdvancedPanel_SystemThemeChanged;
            advancedPanel.RippleEffectStarted += AdvancedPanel_RippleEffectStarted;
            advancedPanel.VisualStyleChanged += AdvancedPanel_VisualStyleChanged;
            advancedPanel.KeyboardFocusReceived += AdvancedPanel_KeyboardFocusReceived;

            Controls.Add(advancedPanel);
        }

        private void AdvancedPanel_SystemThemeChanged(object sender, SiticoneAdvancedPanel.SystemThemeChangedEventArgs e)
        {
            // Handle theme change
            MessageBox.Show($"System theme changed to: {e.NewTheme}");
        }

        private void AdvancedPanel_RippleEffectStarted(object sender, SiticoneAdvancedPanel.RippleEffectEventArgs e)
        {
            // Handle ripple effect start
            Console.WriteLine($"Ripple effect started at: {e.Origin}");
        }

        private void AdvancedPanel_VisualStyleChanged(object sender, SiticoneAdvancedPanel.VisualStyleChangedEventArgs e)
        {
            // Handle visual style changes
            Console.WriteLine($"Visual style property changed: {e.PropertyName}");
        }

        private void AdvancedPanel_KeyboardFocusReceived(object sender, SiticoneAdvancedPanel.KeyboardFocusEventArgs e)
        {
            // Handle keyboard focus changes
            Console.WriteLine($"Keyboard focus received: {e.HasFocus}");
        }

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

Unsubscribing from Events

When disposing of the control or changing contexts, you might need to unsubscribe from events to prevent memory leaks:

// In your form's Dispose or closing logic
advancedPanel.SystemThemeChanged -= AdvancedPanel_SystemThemeChanged;
advancedPanel.RippleEffectStarted -= AdvancedPanel_RippleEffectStarted;
advancedPanel.VisualStyleChanged -= AdvancedPanel_VisualStyleChanged;
advancedPanel.KeyboardFocusReceived -= AdvancedPanel_KeyboardFocusReceived;

---

Key Points

Aspect	Details
Notification	Events provide real-time notifications for system theme changes, ripple effect initiation, visual style updates, and keyboard focus.
Extensibility	By handling events, you can extend the control's behavior without modifying its core functionality.
Ease of Integration	Subscribing to and handling these events is straightforward, using standard .NET event patterns.

---

Best Practices

Recommendation	Explanation
Unsubscribe from Events	Always unsubscribe from events when the control is disposed to prevent memory leaks in long-running applications.
Keep Event Handlers Efficient	Ensure that event handlers execute quickly to avoid UI lag or performance bottlenecks.
Log or Visualize Event Data	Utilize logging or visual feedback in event handlers (e.g., message boxes or console outputs) during development for easier debugging.

---

Common Pitfalls

Pitfall	How to Avoid It
Memory Leaks	Failing to unsubscribe from events can cause memory leaks; unsubscribe in Dispose or FormClosing events.
Overcomplicated Handlers	Avoid adding complex logic directly in event handlers; delegate to separate methods or services for maintainability.
Ignoring Event Data	Not using the provided event data (e.g., theme type or ripple origin) may lead to missed opportunities for enhanced UX.

---

Usage Scenarios

Scenario	Description
Adaptive Theming	React to system theme changes to update the control's appearance automatically in real-time.
Interactive Feedback	Trigger animations or other UI changes when the panel receives keyboard focus or starts a ripple effect.
Debugging and Logging	Use visual style change events to log property updates for troubleshooting and development insights.

---

Review

Review Point	Key Consideration
Responsiveness	Events and Callback facilitate a responsive UI by notifying developers of critical state changes.
Simplicity	The standard .NET event pattern makes integrating these callbacks straightforward and familiar.
Extendibility	Handling these events allows for further customization of the control's behavior without modifying its internals.

---

Summary

Events and Callback in the SiticoneAdvancedPanel control provide essential hooks for developers to respond to changes in system theme, initiate ripple effects, update visual styles, and monitor keyboard focus. By properly subscribing to these events, you can enhance interactivity, improve debugging, and create dynamic, responsive user interfaces.

---

Additional Sections

Troubleshooting

Issue	Possible Cause	Suggested Solution
Event Not Firing	The event may not be subscribed correctly or the control's state hasn't changed as expected.	Verify event subscriptions and simulate user interactions (e.g., focus changes or mouse events) to trigger events.
Performance Issues in Handlers	Complex or long-running logic in event handlers can slow down the UI.	Refactor heavy logic into background tasks or separate methods, keeping event handlers lightweight.

---

Integration Checklist

Step	Description
Subscribe to Events	Attach event handlers for SystemThemeChanged, RippleEffectStarted, VisualStyleChanged, and KeyboardFocusReceived.
Implement Efficient Handlers	Ensure that each event handler is concise and performs only necessary operations.
Test Across Scenarios	Simulate various user interactions and system changes to ensure that all events fire as expected.
Unsubscribe When Necessary	Properly unsubscribe from events during control disposal or context changes to prevent memory leaks.

---

This comprehensive documentation for Events and Callback in the SiticoneAdvancedPanel control is intended to help developers implement and manage event-driven behavior in their applications. By following these guidelines and examples, you can effectively harness the control’s built-in events to create interactive, dynamic user interfaces.