Behavior & Target Copy

This feature governs how the control interacts with user inputs to copy text from a target control and provides methods for identifying valid copy targets.

Overview

The Behavior & Target Copy Functionality feature manages the core operations of the SiticoneCopyButton. It defines how the control initiates and executes the copy process—including click and keyboard handling—and identifies the control whose text is to be copied, ensuring a seamless copy-to-clipboard experience.

---

Detailed Documentation

Properties & Settings

The table below outlines the customizable properties and methods related to the copy functionality and target behavior:

Property/Method	Description	Default Value	Type	Example Usage
TargetControl	Specifies the control whose text content is copied when the button is clicked; the target must have a readable Text property.	(Not set)	Control	copyButton.TargetControl = myTextBox;
GetAvailableTargetControls(Action)	Enumerates the names of valid target controls (i.e., those with a Text property) from the parent container to assist in dynamic selection.	–	Method	copyButton.GetAvailableTargetControls(name => Console.WriteLine(name));
GetValidTargetControls	Returns an array of valid controls from the parent container that have a Text property, for easier runtime validation of potential targets.	–	Method	Control[] validTargets = copyButton.GetValidTargetControls();

---

Code Examples and Integration Demos

Basic Integration Example

The following example demonstrates how to configure the Behavior & Target Copy Functionality by assigning a target control from which text is copied:

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

namespace BehaviorCopyDemo
{
    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 is the text to be copied."
            };

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

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

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

Advanced Copy Functionality Example

This advanced example shows how to leverage the target control validation methods and handle multiple potential copy sources in a dynamic environment:

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

namespace AdvancedBehaviorCopyDemo
{
    public class CustomForm : Form
    {
        private SiticoneCopyButton copyButton;
        private TextBox sourceTextBox1;
        private TextBox sourceTextBox2;

        public CustomForm()
        {
            InitializeComponents();
            ListValidTargets();
        }

        private void InitializeComponents()
        {
            // Create and configure the first source TextBox
            sourceTextBox1 = new TextBox
            {
                Location = new Point(20, 20),
                Width = 250,
                Text = "First copy source."
            };

            // Create and configure the second source TextBox
            sourceTextBox2 = new TextBox
            {
                Location = new Point(20, 60),
                Width = 250,
                Text = "Second copy source."
            };

            // Create and configure the SiticoneCopyButton with the first source as default
            copyButton = new SiticoneCopyButton
            {
                Location = new Point(20, 100),
                Size = new Size(200, 40),
                Text = "Copy",
                TargetControl = sourceTextBox1
            };

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

        private void ListValidTargets()
        {
            // Display valid target control names in the console
            copyButton.GetAvailableTargetControls(name =>
            {
                Console.WriteLine($"Valid target found: {name}");
            });
        }

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

---

Key Points

Aspect	Details
Target Validation	The control validates that the assigned TargetControl has a readable Text property to ensure reliable copy operations.
Input Handling	Supports click and keyboard inputs (Space/Enter) to trigger the copy process.
Copy Process Resilience	Implements click debouncing and cancellation tokens to handle rapid sequential copy attempts gracefully.

---

Best Practices

Practice	Recommendation
Verify TargetControl Assignment	Always set the TargetControl property to a control with a valid Text property to avoid runtime exceptions.
Handle Multiple Copy Sources	Use GetValidTargetControls to dynamically list and choose among potential targets in complex forms.
Optimize Copy Interaction Timing	Leverage the built-in debouncing (CLICK_DEBOUNCE_MS) to prevent unintended multiple copy operations in rapid succession.
Test Keyboard Interactions	Ensure that the control handles both mouse and keyboard events by testing with Space and Enter keys for accessibility.

---

Common Pitfalls

Issue	Explanation	Avoidance Strategy
Unassigned TargetControl	Failing to set the TargetControl property results in a warning message and disables the copy operation.	Always assign a valid control with a Text property to TargetControl before using the copy functionality.
Invalid Target Control Type	Setting TargetControl to a control without a readable Text property can throw an exception.	Verify the target control's type and properties before assignment.
Rapid Multiple Clicks	Multiple fast clicks might attempt concurrent copy operations, possibly leading to unexpected behavior.	Rely on the built‑in click debouncing mechanism; avoid overriding default timing settings.

---

Usage Scenarios

Scenario	Description	Sample Configuration
Single-Source Copy	A straightforward scenario where the button copies text from one clearly defined source control.	Assign a TextBox with sample text to TargetControl and configure basic appearance settings.
Multi-Source Selection	In forms with several candidate text sources, dynamically list and allow selection of valid targets using helper methods.	Use GetAvailableTargetControls to list names; let developers programmatically select a target control.
Keyboard-Driven Copy Operations	Enabling accessibility by ensuring that both mouse and keyboard (Space/Enter) trigger the copy action consistently.	Test with both mouse click events and keyboard events to ensure identical behavior.

---

Review

Aspect	Considerations
Robustness	The control’s built‑in mechanisms (debouncing, cancellation tokens) ensure a resilient copy operation.
Flexibility	The ability to dynamically identify valid target controls simplifies integration in complex forms.
Accessibility	Supports both mouse and keyboard interactions, enhancing accessibility for a diverse user base.
Developer Guidance	Code examples and helper methods (GetAvailableTargetControls, GetValidTargetControls) streamline integration.

---

Summary

Summary Point	Description
Reliable Copy Operations	The Behavior & Target Copy Functionality feature manages a resilient copy process with built‑in safeguards and validation.
Dynamic Target Identification	Methods to list and validate potential copy sources enable flexible integration in multi‑control environments.
Seamless Interaction	Supports both mouse and keyboard triggers, ensuring broad accessibility and user-friendly interaction.

---

Additional Useful Sections

Integration Checklist

Item	Check
Set TargetControl	Ensure that TargetControl is assigned to a valid control with a readable Text property.
Validate Input Handling	Test both mouse clicks and keyboard events (Space/Enter) to verify proper triggering of the copy operation.
Use Helper Methods	Utilize GetAvailableTargetControls and GetValidTargetControls to identify and validate copy targets.
Monitor Debouncing	Verify that rapid multiple clicks do not lead to multiple overlapping copy operations.

Troubleshooting

Problem	Potential Cause	Suggested Fix
No Copy Occurring	TargetControl not set or set to a control lacking a Text property.	Assign a valid control to TargetControl; use GetValidTargetControls to verify.
Inconsistent Copy Behavior	Rapid repeated clicks causing overlap in copy operations.	Rely on the built‑in click debouncing or consider adding additional UI feedback.
Unresponsive Keyboard Trigger	Keyboard events not being handled correctly due to focus issues.	Ensure the control has focus and test using both Space and Enter keys.

---

By following this extensive documentation and using the provided code examples, developers can efficiently integrate and customize the Behavior & Target Copy Functionality of the SiticoneCopyButton control. This ensures a reliable, accessible, and seamless copy-to-clipboard experience in WinForms applications.