Events and Callbacks

A feature that enables developers to attach custom logic to key control state changes and user interactions through events and callbacks.

Overview

The Events and Callbacks feature in the SiticoneNotificationButton control exposes several events that allow developers to hook into the control's internal processes. This facilitates the integration of custom behavior when specific interactions occur, such as changes in the mute state, completion of animations, or detection of gesture-based actions. By subscribing to these events or providing callbacks, developers can extend the functionality of the control to better integrate with the overall application logic.

---

Key Points

Aspect	Details
Mute State Changes	The MuteStateChanged event is raised whenever the bell icon's mute state toggles.
Animation Completion	The ParticleAnimationCompleted and HoverAnimationCompleted events notify developers when the corresponding animations have finished.
Gesture Detection	The LongPress event signals the detection of a long-press gesture, allowing for custom context-specific actions.
Callbacks Integration	Developers can attach custom callbacks to these events to run specific code when these events occur, thereby enhancing control behavior.

---

Best Practices

Best Practice	Explanation
Subscribe only to needed events	Attach callbacks only to events that are relevant to your application logic to minimize overhead and maintain clarity in your code.
Keep event handlers lightweight	Ensure that the code in your event handlers runs quickly to avoid blocking the UI thread; delegate lengthy operations to background tasks if needed.
Detach event handlers when no longer needed	To prevent memory leaks and unintended behavior, unsubscribe from events when controls are disposed or when callbacks are no longer required.
Use clear naming conventions for callbacks	Organize your callback methods with clear, descriptive names to facilitate easier maintenance and debugging of the event-driven code.

---

Common Pitfalls

Pitfall	Explanation	Recommendation
Over-subscribing to events	Attaching too many event handlers can lead to performance degradation and increased complexity in your code.	Only subscribe to events that are essential for your specific application requirements.
Neglecting to detach event handlers	Failing to unsubscribe from events may cause memory leaks, particularly in long-running applications.	Always unsubscribe in the Dispose method or when the control is removed from the UI.
Blocking the UI thread in event handlers	Heavy or synchronous processing in event callbacks can make the UI unresponsive.	Offload processing to background threads or use asynchronous programming patterns when possible.
Ignoring error handling in callbacks	Errors in event handlers can go unnoticed and affect the overall application performance or stability.	Implement try-catch blocks or proper error handling within your event handlers.

---

Usage Scenarios

Scenario	When to Use
Updating UI elements dynamically	When a change in the control's state (such as muting) should trigger updates in other parts of the UI.
Chaining animations or actions	To start a follow-up animation or execute additional logic after a visual effect (e.g., after particle or hover animation completes).
Integrating gesture-based functionality	When a long-press gesture should reveal extra options or context menus, using the LongPress event to trigger custom actions.
Logging and analytics	To capture user interaction data (like toggling mute or animation completions) for monitoring and analysis purposes.

---

Code Examples

Example 1: Mute State Change Callback

This example demonstrates how to subscribe to the MuteStateChanged event and execute a callback to update a UI label accordingly.

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

public class EventsAndCallbacksForm : Form
{
    private SiticoneNotificationButton notificationButton;
    private Label muteStatusLabel;

    public EventsAndCallbacksForm()
    {
        notificationButton = new SiticoneNotificationButton
        {
            Location = new Point(50, 50),
            Size = new Size(50, 50),
            CanMute = true,
            NotificationTooltip = "Click to toggle mute"
        };

        // Subscribe to the mute state change event
        notificationButton.MuteStateChanged += OnMuteStateChanged;

        muteStatusLabel = new Label
        {
            Location = new Point(50, 120),
            AutoSize = true,
            Text = "Mute state: Unmuted"
        };

        Controls.Add(notificationButton);
        Controls.Add(muteStatusLabel);
    }

    private void OnMuteStateChanged(object sender, EventArgs e)
    {
        // Update the UI label based on the new mute state
        muteStatusLabel.Text = $"Mute state: {(notificationButton.IsMuted ? "Muted" : "Unmuted")}";
    }

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

Example 2: Particle Animation Completion Callback

This example shows how to handle the ParticleAnimationCompleted event to perform an action once the particle effect animation has finished.

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

public class ParticleAnimationCallbackForm : Form
{
    private SiticoneNotificationButton notificationButton;

    public ParticleAnimationCallbackForm()
    {
        notificationButton = new SiticoneNotificationButton
        {
            Location = new Point(50, 50),
            Size = new Size(50, 50),
            EnableParticles = true,
            ParticleCount = 20,
            ParticleSpeed = 3f,
            NotificationTooltip = "Click to trigger particle animation"
        };

        // Subscribe to the particle animation completed event
        notificationButton.ParticleAnimationCompleted += OnParticleAnimationCompleted;

        Controls.Add(notificationButton);
    }

    private void OnParticleAnimationCompleted(object sender, EventArgs e)
    {
        MessageBox.Show("Particle animation completed.", "Animation Callback");
    }

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

Example 3: Handling Multiple Events with Callbacks

This example demonstrates attaching callbacks to both the LongPress and HoverAnimationCompleted events to trigger distinct actions.

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

public class MultiEventCallbackForm : Form
{
    private SiticoneNotificationButton notificationButton;

    public MultiEventCallbackForm()
    {
        notificationButton = new SiticoneNotificationButton
        {
            Location = new Point(50, 50),
            Size = new Size(50, 50),
            LongPressDuration = 1000, // Set a 1-second long-press duration
            NotificationTooltip = "Hold to trigger long press, hover for animation"
        };

        // Subscribe to both the LongPress and HoverAnimationCompleted events
        notificationButton.LongPress += OnLongPressDetected;
        notificationButton.HoverAnimationCompleted += OnHoverAnimationCompleted;

        Controls.Add(notificationButton);
    }

    private void OnLongPressDetected(object sender, EventArgs e)
    {
        MessageBox.Show("Long press detected. Initiating extended action.", "Long Press Callback");
    }

    private void OnHoverAnimationCompleted(object sender, EventArgs e)
    {
        Console.WriteLine("Hover animation has completed. You can now trigger follow-up actions.");
    }

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

---

Review

The Events and Callbacks feature provides a powerful mechanism to integrate custom logic into the SiticoneNotificationButton control. By leveraging events like MuteStateChanged, ParticleAnimationCompleted, HoverAnimationCompleted, and LongPress, developers can build highly responsive and interactive applications. The use of callbacks helps decouple the control’s internal logic from external behavior, ensuring maintainable and scalable code.

---

Summary

The Events and Callbacks feature allows developers to extend the functionality of the SiticoneNotificationButton control by hooking into key state changes and interactions. By subscribing to events and attaching custom callbacks, you can seamlessly integrate additional application logic—whether it’s updating the UI, triggering animations, or logging user interactions—enhancing the overall user experience.

---

Additional Notes

Note	Details
Event Lifecycle Management	Ensure that event subscriptions are properly managed to avoid memory leaks by unsubscribing when the control is disposed.
Asynchronous Event Handling	Consider employing asynchronous patterns in event handlers if they perform time-consuming operations to keep the UI responsive.
Integration with Application Logic	Use events and callbacks as triggers for other parts of your application, such as updating state, logging, or interfacing with other controls.

---

Usage Scenarios Recap

Scenario	When to Use
Dynamic UI updates	To update UI components or trigger animations based on the control’s internal state changes, such as muting or animation completion.
Custom gesture and animation actions	When user interactions (like long-press gestures) should initiate context-specific actions or open additional options.
Logging and diagnostics	To log user interactions or animation completions for analytics or debugging purposes, leveraging event callbacks.

By following this comprehensive documentation and utilizing the provided code examples, developers can effectively integrate and leverage the Events and Callbacks features of the SiticoneNotificationButton control, ensuring a dynamic, responsive, and well-integrated experience in their .NET WinForms applications.