Events and Callbacks

This feature describes how the control responds to user interactions and how developers can hook into standard events to extend or customize behavior.

Overview

The Events and Callbacks feature describes the control’s built‑in event handling for mouse, keyboard, and focus interactions. While many behaviors (such as animations, copy operations, and notifications) are handled internally, the control exposes standard Windows Forms events so that developers can respond to user actions or supplement the copy process with custom logic.

---

Detailed Documentation

Available Events

The table below summarizes the key events that the control exposes through its inheritance from System.Windows.Forms.Control. These events allow developers to execute custom code before, during, or after the copy operation and related visual feedback:

Event	Description	Source/Class	Example Usage
Click	Occurs when the control is clicked; triggers the copy operation along with animations and notifications.	System.Windows.Forms.Control	copyButton.Click += (s, e) => { /* custom logic */ };
MouseEnter	Fires when the mouse pointer enters the control’s bounds, allowing custom hover behaviors.	System.Windows.Forms.Control	copyButton.MouseEnter += (s, e) => { /* custom hover logic */ };
MouseLeave	Fires when the mouse pointer leaves the control, enabling custom exit or reset logic.	System.Windows.Forms.Control	copyButton.MouseLeave += (s, e) => { /* custom logic */ };
MouseDown	Occurs when a mouse button is pressed on the control; used internally to initiate animations like scaling and ripple effects.	System.Windows.Forms.Control	copyButton.MouseDown += (s, e) => { /* additional processing */ };
MouseUp	Fires when the mouse button is released; signals the end of a press event and may trigger the copy if within bounds.	System.Windows.Forms.Control	copyButton.MouseUp += (s, e) => { /* extra actions */ };
KeyDown	Occurs when a key is pressed while the control has focus; typically used to start the copy operation on Space/Enter.	System.Windows.Forms.Control	copyButton.KeyDown += (s, e) => { /* custom key logic */ };
KeyUp	Fires when a key is released; helps finalize the copy action when using keyboard inputs.	System.Windows.Forms.Control	copyButton.KeyUp += (s, e) => { /* custom processing */ };
GotFocus / LostFocus	Provide notifications when the control gains or loses focus, useful for managing visual focus cues and accessibility.	System.Windows.Forms.Control	copyButton.GotFocus += (s, e) => { /* focus gained */ };

Note: The SiticoneCopyButton does not define additional custom events for the copy operation (such as CopyCompleted) as its internal asynchronous operations (animations, notifications, and copy logic) are managed internally. Developers can utilize the standard events to integrate any additional callbacks if required.

---

Internal Callbacks and Asynchronous Operations

Internally, the control employs callbacks within asynchronous tasks to manage:

Internal Operation	Description	Developer Access	Example Considerations
Copy Operation	The asynchronous method PerformCopy() uses cancellation tokens and debouncing to ensure a robust copy-to-clipboard action.	Not directly exposed	Custom logic can be added via the Click event.
Animation Sequences	Methods such as AnimateCheckmark(), StartRippleEffect(), and scaling tasks are invoked to provide visual feedback.	Not directly exposed	Rely on standard events for additional UI feedback.
Notification Display	Methods ShowNotification() and CloseNotification() handle the animated popup to confirm copy completion.	Not directly exposed	Ensure that notification properties are correctly set.

These internal callbacks are designed to be self‑contained; however, developers can monitor or chain additional actions using the exposed events.

---

Code Examples and Integration Demos

Basic Event Handling Example

This example demonstrates how to subscribe to the standard Click event to add custom logic after the copy operation is initiated:

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

namespace EventHandlingDemo
{
    public class MainForm : Form
    {
        private SiticoneCopyButton copyButton;
        private TextBox sourceTextBox;

        public MainForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            // Create and configure the source TextBox
            sourceTextBox = new TextBox
            {
                Location = new Point(20, 20),
                Width = 250,
                Text = "This text will be copied."
            };

            // Create and configure the SiticoneCopyButton
            copyButton = new SiticoneCopyButton
            {
                Location = new Point(20, 60),
                Size = new Size(200, 40),
                Text = "Copy",
                TargetControl = sourceTextBox
            };

            // Subscribe to the Click event to perform additional actions
            copyButton.Click += CopyButton_Click;

            // Add controls to the form
            Controls.Add(sourceTextBox);
            Controls.Add(copyButton);
        }

        private void CopyButton_Click(object sender, EventArgs e)
        {
            // Custom logic that runs after the copy operation starts
            MessageBox.Show("The copy operation has been initiated.", "Info", MessageBoxButtons.OK, MessageBoxIcon.Information);
        }

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

Advanced Event Handling with Keyboard Support

This example shows how to attach both mouse and keyboard event handlers to provide a seamless and accessible experience:

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

namespace AdvancedEventHandlingDemo
{
    public class CustomForm : Form
    {
        private SiticoneCopyButton copyButton;
        private TextBox demoTextBox;

        public CustomForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            demoTextBox = new TextBox
            {
                Location = new Point(30, 30),
                Width = 300,
                Text = "Advanced event handling demo text."
            };

            copyButton = new SiticoneCopyButton
            {
                Location = new Point(30, 80),
                Size = new Size(250, 50),
                Text = "Advanced Copy",
                TargetControl = demoTextBox
            };

            // Attach mouse event handlers
            copyButton.MouseEnter += (s, e) =>
            {
                // Custom behavior on mouse hover (e.g., logging or additional visual cues)
                Console.WriteLine("Mouse entered the copy button.");
            };

            // Attach keyboard event handlers to support accessibility
            copyButton.KeyDown += (s, e) =>
            {
                if (e.KeyCode == Keys.Enter || e.KeyCode == Keys.Space)
                {
                    Console.WriteLine("Keyboard event detected; initiating copy operation.");
                }
            };

            // Subscribe to the Click event for additional custom logic
            copyButton.Click += (s, e) =>
            {
                Console.WriteLine("Copy button clicked.");
            };

            Controls.Add(demoTextBox);
            Controls.Add(copyButton);
        }

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

---

Key Points

Aspect	Details
Standard Events	The control exposes standard mouse, keyboard, and focus events inherited from System.Windows.Forms.Control.
Customization Flexibility	Developers can attach custom event handlers to extend or supplement the built‑in copy and animation logic.
Internal Asynchronous Operations	Internal callbacks manage animations and notifications, ensuring a responsive and non‑blocking copy operation.
Accessibility Support	Keyboard events (KeyDown, KeyUp) and focus events (GotFocus, LostFocus) help in creating an accessible UI.

---

Best Practices

Practice	Recommendation
Leverage Standard Events	Utilize the Click, Mouse, and Key events to add custom logic without interfering with the control’s internal operations.
Avoid Interference with Internal Logic	Refrain from overriding the internal asynchronous copy and animation callbacks; instead, add complementary behaviors via event handlers.
Test Under Different Interaction Modes	Ensure that custom event handlers function properly for both mouse and keyboard interactions.
Maintain Accessibility	When adding custom logic, preserve the default behavior that supports accessibility (e.g., focus cues, keyboard activation).

---

Common Pitfalls

Issue	Explanation	Avoidance Strategy
Interfering with Internal Callbacks	Overriding or blocking standard events may disrupt internal animations and notifications.	Attach additional event handlers without overriding the default behavior; use additive logic only.
Inconsistent Event Behavior	Custom event handlers that modify focus or input handling may lead to inconsistent behavior across different interaction modes.	Test event handlers thoroughly with both mouse and keyboard interactions.
Overcomplicating Event Chains	Adding too many custom callbacks can lead to unpredictable event chains and degraded performance.	Keep custom event logic modular and minimal to complement the built‑in functionality.

---

Usage Scenarios

Scenario	Description	Sample Configuration/Usage
Custom Notification After Copy	Adding a custom MessageBox or log entry after the copy operation is initiated via the Click event.	Attach a handler to the Click event that shows a MessageBox, as demonstrated in the basic event handling example.
Logging User Interactions	Recording detailed logs for debugging or analytics by subscribing to MouseEnter, MouseLeave, and Key events.	Use event handlers to write to the console or a log file when specific events are fired.
Enhancing Accessibility	Supplementing default keyboard interactions with additional visual cues or sounds by subscribing to KeyDown/KeyUp events.	Attach custom logic to keyboard events to provide auditory feedback or to trigger auxiliary UI updates.

---

Review

Aspect	Considerations
Integration Simplicity	The control’s reliance on standard Windows Forms events makes it straightforward to integrate with existing logic.
Flexibility and Extensibility	Developers can easily attach their own callbacks without interfering with the control’s internal animations and copy logic.
Maintainability	Keeping custom event handlers separate from the internal logic ensures easier maintenance and debugging.
Accessibility Assurance	Using both mouse and keyboard events ensures that the control remains accessible to all users, including those with disabilities.

---

Summary

Summary Point	Description
Standard and Extensible Events	The Events and Callbacks feature leverages standard Windows Forms events to allow custom logic while preserving internal copy and animation behaviors.
Customizable Interaction	Developers can attach event handlers to enhance the control’s responsiveness and add custom actions alongside built‑in functionality.
Accessible and Consistent	By supporting both mouse and keyboard interactions, the control maintains a consistent and accessible user experience.

---

Additional Useful Sections

Integration Checklist

Item	Check
Subscribe to Key Events	Attach custom event handlers for Click, MouseEnter, MouseLeave, KeyDown, and KeyUp as needed.
Avoid Overriding Internal Operations	Ensure that custom event logic complements, rather than replaces, the control’s built‑in asynchronous callbacks.
Test Across Interaction Modes	Validate that custom event handlers work correctly for both mouse and keyboard interactions.
Preserve Accessibility	Confirm that additional event handlers do not interfere with focus cues and keyboard navigation.

Troubleshooting

Problem	Potential Cause	Suggested Fix
Missing Event Triggers	Custom event handlers may not be attached properly, or the control’s focus might not be set.	Verify that event subscriptions are in place and that the control is focusable.
Conflicts with Internal Animations	Custom logic that inadvertently interferes with the control’s internal copy or animation routines.	Separate custom event logic from internal processing; use additive logic without overriding defaults.
Inconsistent Behavior Across Devices	Variations in input devices or screen configurations may result in different event firing sequences.	Test the control on multiple devices and input methods, adjusting event handlers as necessary.

---

By following this extensive documentation and using the provided code examples, developers can efficiently integrate and customize the Events and Callbacks behavior of the SiticoneCopyButton control. This ensures that additional custom logic can be seamlessly integrated with the control’s built‑in copy and animation processes, providing a robust and accessible user experience in WinForms applications.