Events and Callbacks

This feature exposes a rich set of events that allow developers to integrate custom logic and behaviors into the control’s lifecycle, ensuring seamless synchronization with specific requirements, etc.

Overview

Events for Custom Integration provide hooks into the control’s operations—from input progression and validation to state changes and visual formatting. These events enable developers to react in real time to user interactions and internal changes, thereby facilitating custom processing, logging, and UI updates.

---

Key Points

Key Point	Description
Input Completion	The InputCompleted event signals that all digit boxes have been filled, delivering both numeric and string representations of the entered code.
Digit-Level Feedback	The DigitEntered and DigitCleared events provide granular notifications whenever a digit is entered or removed, allowing for real-time processing and UI updates.
Selection Change Notification	The SelectionChanged event notifies subscribers when the active digit box changes, enabling custom navigation or focus behaviors.
Auto-Clear Warnings	The AutoClearWarning event provides a pre-clear countdown, giving developers the opportunity to cancel the auto-clear if needed.
Value and Format Updates	The ValueChanged and FormattedCodeChanged events allow custom logic to respond whenever the overall input value or its formatted presentation is updated.
Dynamic Sizing Feedback	The SizeRequested event informs subscribers about the dynamically calculated size of the control, enabling better layout management in complex UIs.
Input Validation Notifications	The ValidationFailed event raises alerts when invalid input is detected, delivering detailed information on the index and value of each invalid character.

---

Best Practices

Best Practice	Recommendation
Integrate Early in the Input Lifecycle	Subscribe to input events (e.g., DigitEntered and ValueChanged) early in the control’s lifecycle to ensure that any user interaction triggers the desired custom behaviors immediately.
Use Detailed Event Data	Leverage the rich event arguments provided by events such as InputCompleted and ValidationFailed to log detailed diagnostics or to prompt users with specific corrective actions.
Implement Robust Error Handling	Use the AutoClearWarning and ValidationFailed events to implement fallback or correction logic, ensuring that users are informed and guided when input does not meet expected standards.
Coordinate UI Updates with Size and Format Changes	Use the SizeRequested and FormattedCodeChanged events to synchronize custom UI elements with the control’s dynamic layout and formatting updates, ensuring consistency across the application.

---

Common Pitfalls

Pitfall	Explanation	Mitigation
Ignoring Partial Input Feedback	Failing to handle events such as DigitEntered or DigitCleared may leave the application unaware of changes in input, causing UI elements to fall out of sync.	Always subscribe to input-related events to keep the UI updated in real time.
Overlooking Event Cancellation Opportunities	Not handling the AutoClearWarning event properly might result in unintended data clearance during critical user operations.	Implement cancellation logic in the AutoClearWarning event to allow the application to postpone auto-clear based on user interaction or context.
Inconsistent Event Handling	Handling events in an inconsistent or delayed manner may lead to glitches, such as incorrect formatting or delayed validations.	Ensure that event handlers are efficient and update the UI or business logic synchronously with the control’s state changes.
Redundant Subscriptions	Subscribing to the same event multiple times or without proper cleanup can cause unexpected behavior and performance issues.	Carefully manage event subscriptions, especially in dynamic UI scenarios, to avoid multiple handlers performing the same actions.

---

Usage Scenarios

Scenario	Description	Implementation Example
Processing Completed Input	After the user fills all digit boxes, process the input code immediately for authentication, verification, or submission.	Subscribe to the InputCompleted event to trigger the next step in the authentication flow once the code is fully entered.
Providing Instant Digit Feedback	Update a visual indicator or log changes as each digit is entered or cleared, offering immediate feedback to users and tracking the input process.	Use the DigitEntered and DigitCleared events to update a progress bar or log entries that reflect real-time changes in the input.
Customizing Navigation Behavior	Change the focus or visual highlighting when the active digit box changes, facilitating a tailored navigation experience within the control.	Handle the SelectionChanged event to customize navigation logic or to update visual cues that guide the user through the digit boxes.
Preempting Auto-Clear Actions	Before the control auto-clears sensitive input, warn the user or delay the clearance based on application-specific criteria.	Use the AutoClearWarning event to intercept the auto-clear process and implement custom logic to cancel or postpone the clearance.
Adapting to Dynamic Size Changes	Adjust surrounding UI elements based on the control’s calculated size, ensuring consistent layout and alignment in responsive interfaces.	Subscribe to the SizeRequested event to receive the control’s size updates and resize or reposition related elements accordingly.
Logging and Debugging Input Validation	Track and respond to invalid input attempts by logging detailed information, thereby enabling easier debugging and better user feedback.	Handle the ValidationFailed event to log the index and value of each invalid character and to display custom error messages or guidance to the user.

---

Code Examples

Example 1: Processing Input Completion

// Create an instance of the control
SiticoneOtp otpControl = new SiticoneOtp();

// Subscribe to the InputCompleted event to process the complete code
otpControl.InputCompleted += (sender, e) =>
{
    // Retrieve both numeric and string representations
    int codeNumber = e.EnteredCodeAsInt;
    string codeString = e.EnteredCodeAsString;
    Console.WriteLine($"Input complete. Code (string): {codeString}, Code (int): {codeNumber}");
    
    // Proceed with authentication or verification logic
    AuthenticateUser(codeNumber);
};

// A dummy method for demonstration
void AuthenticateUser(int code)
{
    // Custom authentication logic here
    Console.WriteLine($"Authenticating user with code: {code}");
}

// Add the control to your form
this.Controls.Add(otpControl);
otpControl.Location = new Point(50, 50);

Example 2: Responding to Digit-Level Events

// Create an instance of the control
SiticoneOtp otpControl = new SiticoneOtp();

// Subscribe to the DigitEntered event to log and update UI dynamically
otpControl.DigitEntered += (sender, e) =>
{
    Console.WriteLine($"Digit entered at index {e.Index}: {e.Digit}");
    
    // Optionally update a progress indicator based on e.IsComplete flag
    if (e.IsComplete)
    {
        Console.WriteLine("All digits have been entered.");
    }
};

// Subscribe to the DigitCleared event to log and notify the user
otpControl.DigitCleared += (sender, e) =>
{
    Console.WriteLine($"Digit cleared at index {e.Index}. Previous value was '{e.PreviousValue}'.");
};

// Add the control to your form
this.Controls.Add(otpControl);
otpControl.Location = new Point(50, 120);

Example 3: Custom Handling of Auto-Clear Warning

// Create an instance of the control
SiticoneOtp otpControl = new SiticoneOtp();

// Enable auto-clear and set a delay
otpControl.AutoClearEnabled = true;
otpControl.AutoClearDelaySeconds = 30;

// Subscribe to the AutoClearWarning event to intercept auto-clear
otpControl.AutoClearWarning += (sender, e) =>
{
    Console.WriteLine($"Warning: Input will be cleared in {e.RemainingSeconds} seconds.");
    
    // Optionally cancel auto-clear based on custom logic
    if (UserIsStillInteracting())
    {
        e.Cancel = true; // Prevent the control from auto-clearing the input
        Console.WriteLine("Auto-clear canceled due to user activity.");
    }
};

bool UserIsStillInteracting()
{
    // Insert logic to determine if the user is active (e.g., checking for recent input or focus state)
    return true;
}

// Add the control to your form
this.Controls.Add(otpControl);
otpControl.Location = new Point(50, 200);

Example 4: Adapting to Dynamic Size Changes

// Create an instance of the control
SiticoneOtp otpControl = new SiticoneOtp();

// Subscribe to the SizeRequested event to adjust surrounding UI components
otpControl.SizeRequested += (sender, size) =>
{
    Console.WriteLine($"Control requested size: {size.Width}x{size.Height}");
    
    // Update a parent container or adjacent control accordingly
    AdjustLayout(size);
};

void AdjustLayout(Size newSize)
{
    // Custom logic to resize or reposition UI elements based on the new size of the control
    Console.WriteLine($"Adjusting layout to accommodate new size: {newSize.Width}x{newSize.Height}");
}

// Add the control to your form
this.Controls.Add(otpControl);
otpControl.Location = new Point(50, 280);

---

Review

Aspect	Evaluation
Integration Flexibility	The events provide comprehensive coverage for all key interactions, enabling developers to integrate custom behaviors that respond dynamically to input and state changes.
Real-Time Feedback	With immediate notifications through events like DigitEntered, ValueChanged, and InputCompleted, the control supports highly responsive user interfaces.
Customization and Control	The range of events allows developers to finely tune the control’s behavior—from navigation and formatting to auto-clear cancellation and validation—ensuring complete custom integration.

---

Summary

Events for Custom Integration in the SiticoneOtp control empower developers to hook into every critical stage of the input process. By handling events that notify input completion, digit changes, auto-clear warnings, and dynamic sizing, developers can build responsive, robust, and user-friendly applications that respond in real time to user actions and system events.

---

Additional Recommendations

Recommendation	Explanation
Centralize Event Handling Logic	Organize your event handlers in a centralized module or class to maintain consistency and reduce code redundancy, especially in complex applications.
Optimize Event Handlers for Performance	Ensure that event handlers execute quickly to avoid UI lag; consider offloading heavy processing to background threads if necessary.
Document Custom Event Logic Thoroughly	Maintain detailed documentation of how each event is handled in your application to facilitate future maintenance and onboarding of new developers.
Test Across Edge Cases and User Interactions	Rigorously test the event-driven behaviors under different user scenarios to ensure that the control behaves as expected, particularly during rapid or concurrent interactions.

By following these guidelines and utilizing the provided code examples, developers can fully leverage the event-driven capabilities of the SiticoneOtp control for custom integration, ensuring that every user interaction is captured and processed in a manner that meets the application’s unique requirements.