Additional Public Methods

Additional Public Methods provide utility functions that allow developers to programmatically manage and interact with the control, offering enhanced control over its behavior and appearance.

Overview

The Additional Public Methods feature encompasses several key methods that enhance the functionality of the SiticoneOtp control. These methods include clearing the input, validating the entered code against a custom pattern, formatting the code with custom separators and placeholders, performing type-safe conversions, and customizing the appearance through corner radius adjustments. These methods simplify common tasks, enabling developers to integrate and manipulate the control with minimal effort.

---

Key Points

Key Point	Description
Clear()	Resets the control by clearing all digit boxes and restoring the initial state, ensuring the control is ready for fresh input.
ValidateCode(string)	Validates the entered code against a custom regular expression pattern, ensuring the code meets specific formatting requirements.
GetFormattedCode()	Generates a formatted string version of the entered code, inserting custom separators and placeholders for missing digits for improved clarity.
TryGetCodeAs()	Attempts to convert the entered code into the specified type (e.g., int, long, string) safely, providing a flexible data extraction mechanism.
SetCornerRadii()	Allows for simultaneous setting of all four corner radii to customize the appearance of the digit boxes, offering precise visual control.

---

Best Practices

Best Practice	Recommendation
Reset Input Before New Data Entry	Use the Clear() method to ensure that the control is in a known, empty state before accepting new input, which helps prevent data corruption.
Validate Early and Often	Invoke ValidateCode() to check that the input conforms to expected patterns, especially when user input is critical (e.g., in authentication workflows).
Leverage Formatted Output	Utilize GetFormattedCode() to display the input in a user-friendly manner, ensuring that missing digits are clearly indicated with placeholders.
Ensure Type-Safe Data Conversion	Use TryGetCodeAs() for type conversions to gracefully handle scenarios where the code may not convert properly, thereby preventing runtime exceptions.
Customize Appearance Consistently	Employ SetCornerRadii() along with individual corner properties to maintain a consistent and attractive UI, ensuring that the control aligns with your application's design language.

---

Common Pitfalls

Pitfall	Explanation	Mitigation
Forgetting to Clear the Control	Not calling Clear() before new input may lead to unintended residual data from previous operations.	Always call Clear() when resetting the control or before initiating a new data entry process.
Skipping Input Validation	Bypassing ValidateCode() might result in processing invalid or malformed input, which could compromise business logic.	Ensure ValidateCode() is invoked after user input and before processing the code, particularly in sensitive applications.
Ignoring Conversion Failures	Directly converting the code without using TryGetCodeAs() can cause exceptions if the input format does not match the expected type.	Always use TryGetCodeAs() and check the result to handle conversion failures gracefully.
Over-customizing Corner Radii	Excessive or inconsistent values passed to SetCornerRadii() may lead to visual distortion and a poor user interface.	Test different values and ensure that the provided radii are within acceptable ranges relative to the digit box dimensions.

---

Usage Scenarios

Scenario	Description	Implementation Example
Clearing the Input for Re-entry	In scenarios where a user has made a mistake or a timeout occurs, use Clear() to reset the control quickly.	Call otpControl.Clear() in response to a button click or timeout event.
Validating a Code for Security Compliance	When a specific format is required (e.g., numeric only), use ValidateCode() to ensure the entered code meets the criteria before submission.	Use bool isValid = otpControl.ValidateCode("^[0-9]+$") and act based on the result.
Displaying a User-Friendly Code Format	Format the entered code for display, using custom separators and placeholders to indicate missing digits, which can improve user understanding.	Call string formattedCode = otpControl.GetFormattedCode("-", '_') and bind it to a label for display.
Safely Converting Code for Processing	Convert the entered code to an integer safely using TryGetCodeAs(), avoiding potential conversion errors.	Use if(otpControl.TryGetCodeAs<int>(out int numericCode)) { /* process numericCode */ } else { /* handle conversion failure */ }
Customizing Box Appearance for Branding	Adjust the appearance of digit boxes to match your application's theme by setting custom corner radii.	Invoke otpControl.SetCornerRadii(10, 5, 5, 10) to apply a custom corner style that aligns with your brand's aesthetics.

---

Code Examples

Example 1: Clearing the Control

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

// Set an initial value (for demonstration)
otpControl.SetValue("123456");

// Clear the control, resetting all digit boxes
otpControl.Clear();

// Optionally, check if the control is empty after clearing
if (otpControl.IsEmpty)
{
    Console.WriteLine("The control has been cleared successfully.");
}

Example 2: Validating the Entered Code

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

// Set the validation pattern (e.g., numeric only)
otpControl.ValidationPattern = "^[0-9]+$";
otpControl.StrictValidation = true;

// Set a sample value
otpControl.SetValue("1234AB");

// Validate the code against the defined pattern
bool isValid = otpControl.ValidateCode(otpControl.ValidationPattern);
Console.WriteLine($"Is the entered code valid? {isValid}");

Example 3: Formatting the Code with Custom Separators

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

// Set a partial value to simulate missing digits (assuming control expects 6 digits)
otpControl.SetValue("12");

// Get the formatted code with a dash separator and underscore as placeholder
string formattedCode = otpControl.GetFormattedCode("-", '_');
Console.WriteLine($"Formatted Code: {formattedCode}");
// Expected output might be: "1-2-_-_-_-_"

Example 4: Safe Type Conversion with TryGetCodeAs

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

// Set a numeric sample value
otpControl.SetValue("987654");

// Attempt to convert the entered code to an integer
if (otpControl.TryGetCodeAs<int>(out int numericCode))
{
    Console.WriteLine($"Numeric Code: {numericCode}");
}
else
{
    Console.WriteLine("Conversion failed. The entered code is not a valid integer.");
}

Example 5: Customizing Digit Box Appearance with SetCornerRadii

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

// Set custom corner radii for a distinct visual style
otpControl.SetCornerRadii(10, 5, 5, 10);

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

---

Review

Aspect	Evaluation
Utility	The additional public methods provide essential functionality to manage the control’s state and appearance, simplifying common tasks like clearing input and formatting data.
Flexibility	With methods supporting both data extraction and visual customization, developers can easily adapt the control to various scenarios and application requirements.
Robustness	Type-safe conversions and custom validation ensure that data integrity is maintained, reducing the risk of runtime errors during data processing.

---

Summary

Additional Public Methods in the SiticoneOtp control empower developers with a suite of utility functions that facilitate the management of the control’s data and appearance. By providing methods to clear input, validate and format data, safely convert types, and customize visual aspects, these methods significantly simplify integration and enhance control over both functionality and presentation.

---

Additional Recommendations

Recommendation	Explanation
Centralize Method Usage in Application Logic	Organize calls to these methods within a dedicated module or controller class to ensure consistency and maintainability across your application.
Test Method Interactions Thoroughly	Verify that each method behaves as expected under various conditions, particularly in edge cases (e.g., incomplete input or invalid formats).
Combine with Event-Driven Updates	Integrate these methods with event handlers (such as ValueChanged or InputCompleted) to automate processing and UI updates in real time as user input changes.
Document Customizations for Future Maintenance	Maintain clear documentation of any customizations made via SetCornerRadii or formatting methods to facilitate future UI updates and ease onboarding of new developers.

By following these guidelines and utilizing the provided code examples, developers can effectively leverage the Additional Public Methods of the SiticoneOtp control to create robust, user-friendly, and visually consistent WinForms applications.