Events and Callbacks

This feature notifies developers when key animations or visual effects, such as particle or hover animations, complete their cycle, enabling further customization and interactivity in the application.

Overview

The Events feature in the SiticoneMenuButton control allows developers to attach custom logic to specific moments during the control's animation cycles. Notably, the control exposes events for when the particle animation and hover animation complete, so that additional actions can be triggered seamlessly in response to these UI events.

---

Feature Details

The following table outlines the available events along with their descriptions:

Event Name	Event Handler Signature	Description
ParticleAnimationCompleted	EventHandler	Raised when the particle animation has finished emitting and all particles have faded.
HoverAnimationCompleted	EventHandler	Raised when the hover animation reaches full opacity and completes its cycle.

---

Code Examples and Samples

Below are detailed code examples illustrating how to subscribe to and handle the Events provided by the SiticoneMenuButton control.

Sample Code: Handling Particle Animation Completion

This example demonstrates how to subscribe to the ParticleAnimationCompleted event to perform an action—such as logging a message or updating UI elements—once the particle animation completes.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Ensure the correct namespace is referenced

namespace ParticleEventDemo
{
    public class MainForm : Form
    {
        private SiticoneMenuButton menuButton;
        private Label lblStatus;

        public MainForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            // Initialize and configure the SiticoneMenuButton
            menuButton = new SiticoneMenuButton
            {
                Size = new Size(60, 60),
                Location = new Point(40, 40),
                EnableParticles = true,   // Enable particle animation effect
                ParticleCount = 20,
                ParticleSpeed = 3f
            };

            // Subscribe to the ParticleAnimationCompleted event
            menuButton.ParticleAnimationCompleted += MenuButton_ParticleAnimationCompleted;

            // Label to display status messages
            lblStatus = new Label
            {
                Text = "Waiting for particle animation to complete...",
                Location = new Point(40, 120),
                AutoSize = true
            };

            Controls.Add(menuButton);
            Controls.Add(lblStatus);

            Text = "Particle Animation Event Demo";
            Size = new Size(300, 250);
            StartPosition = FormStartPosition.CenterScreen;
        }

        private void MenuButton_ParticleAnimationCompleted(object sender, EventArgs e)
        {
            lblStatus.Text = "Particle animation completed!";
            // Additional logic can be executed here (e.g., enabling other controls)
        }

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

Sample Code: Handling Hover Animation Completion

In this example, the HoverAnimationCompleted event is used to trigger an action—such as changing the background color of the form—when the hover animation finishes.

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

namespace HoverEventDemo
{
    public class MainForm : Form
    {
        private SiticoneMenuButton menuButton;

        public MainForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            // Initialize and configure the SiticoneMenuButton
            menuButton = new SiticoneMenuButton
            {
                Size = new Size(60, 60),
                Location = new Point(50, 50),
                EnablePulseEffect = true,   // Ensure hover pulse effect is enabled
                HoverAnimationSpeed = 200
            };

            // Subscribe to the HoverAnimationCompleted event
            menuButton.HoverAnimationCompleted += MenuButton_HoverAnimationCompleted;

            Controls.Add(menuButton);

            Text = "Hover Animation Event Demo";
            Size = new Size(300, 200);
            StartPosition = FormStartPosition.CenterScreen;
        }

        private void MenuButton_HoverAnimationCompleted(object sender, EventArgs e)
        {
            // Change form background color as an example action upon hover animation completion
            this.BackColor = Color.LightCyan;
        }

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

Sample Code: Combining Multiple Event Handlers

This comprehensive example shows how to handle both the particle and hover animation completion events within the same application, providing a more dynamic interactive experience.

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

namespace CombinedEventsDemo
{
    public class MainForm : Form
    {
        private SiticoneMenuButton menuButton;
        private Label lblStatus;

        public MainForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            menuButton = new SiticoneMenuButton
            {
                Size = new Size(60, 60),
                Location = new Point(50, 50),
                EnableParticles = true,
                ParticleCount = 20,
                ParticleSpeed = 3f,
                EnablePulseEffect = true,
                HoverAnimationSpeed = 200
            };

            // Subscribe to both events
            menuButton.ParticleAnimationCompleted += MenuButton_ParticleAnimationCompleted;
            menuButton.HoverAnimationCompleted += MenuButton_HoverAnimationCompleted;

            lblStatus = new Label
            {
                Text = "Animations in progress...",
                Location = new Point(50, 130),
                AutoSize = true
            };

            Controls.Add(menuButton);
            Controls.Add(lblStatus);

            Text = "Combined Events Demo";
            Size = new Size(300, 250);
            StartPosition = FormStartPosition.CenterScreen;
        }

        private void MenuButton_ParticleAnimationCompleted(object sender, EventArgs e)
        {
            lblStatus.Text = "Particle animation finished!";
        }

        private void MenuButton_HoverAnimationCompleted(object sender, EventArgs e)
        {
            // Optionally chain additional effects here
            lblStatus.Text += " Hover animation finished!";
        }

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

---

Key Points

Aspect	Details
Event-Driven Design	The control exposes events to signal when animations complete, allowing for responsive UI updates.
Integration Ease	Simple event handler subscription makes it straightforward to attach custom logic to the control's animations.
Customizability	Developers can combine multiple event handlers to tailor the application's behavior to specific interactions.

---

Best Practices

Practice	Explanation
Always Unsubscribe When Necessary	Prevent memory leaks by unsubscribing from events if the control or form is disposed before the application ends.
Use Events for Chaining Actions	Leverage animation completion events to trigger subsequent actions for a smoother user experience.
Provide User Feedback	Utilize events to update the UI (e.g., status labels, notifications) to inform users of animation completion.

---

Common Pitfalls

Pitfall	How to Avoid
Missing Invalidate() Calls	Ensure Invalidate() is called after property changes to guarantee the control refreshes and events fire correctly.
Overcomplicating Event Handlers	Keep event handler logic simple to maintain responsiveness and avoid performance bottlenecks.
Memory Leaks from Event Subscriptions	Unsubscribe from events appropriately, especially when dealing with long-running forms or dynamic controls.

---

Usage Scenarios

Scenario	How Events Help
Chaining UI Animations	Trigger subsequent UI updates (like enabling controls or changing colors) when an animation completes.
Logging or Analytics	Capture animation completion events for logging user interactions and improving UI/UX analytics.
Dynamic Feedback	Update other UI elements or start new animations based on the completion of particle or hover animations.

---

Review

The Events feature of the SiticoneMenuButton control is a powerful mechanism that enables developers to hook into animation cycles. By handling events such as ParticleAnimationCompleted and HoverAnimationCompleted, developers can extend the functionality of the control, synchronizing UI updates and ensuring a responsive and engaging user experience.

---

Summary

The Events feature empowers developers to react to key animation milestones within the SiticoneMenuButton control. With straightforward event subscription for particle and hover animation completions, integrating these events into your application facilitates dynamic UI updates and richer interactivity. By following best practices and avoiding common pitfalls, you can leverage these events to create a more responsive and intuitive user interface.

---

Additional Sections

Troubleshooting

Issue	Resolution
Event Not Firing	Ensure that the corresponding animation effect is enabled (e.g., EnableParticles or EnablePulseEffect) and that Invalidate() is invoked after property changes.
Delayed Event Handling	Optimize event handler code to avoid long-running tasks; consider using asynchronous patterns if necessary.
Memory Leaks from Events	Properly unsubscribe event handlers during control disposal or form closing to prevent memory leaks.

Future Enhancements

Enhancement	Description
Custom Event Arguments	Introduce custom event argument classes to provide additional data (e.g., animation metrics) during events.
Additional Animation Events	Add more events for other animation milestones (e.g., ripple effect start/finish) for finer control.
Event Chaining Mechanisms	Develop built-in support for chaining events and automating sequential animations based on event triggers.

By following this documentation, developers can effectively implement and harness the Events feature of the SiticoneMenuButton control, enabling the creation of a more interactive and responsive user experience in their .NET WinForms applications.