Public Methods & Text

This feature provides a set of public methods and events that enable developers to programmatically interact with and modify the text content of the control, retrieve and manipulate the numbers, etc.

Overview

The Public Methods & Text Manipulation feature exposes several front‐facing methods that allow you to manipulate the text content, control text selection, and retrieve a sanitized version of the phone number. In addition, events such as TextUpdated are available to notify subscribers when the text changes. These methods enhance the interactivity and integration of the control within your WinForms applications.

Method / Event	Return Type / Event Args	Description
GetRawPhoneNumber()	string	Returns the phone number stripped of all formatting characters, leaving only the digits.
Select(int start, int length)	void	Programmatically selects a range of text within the control based on the provided start index and length.
SelectAll()	void	Selects all text in the control.
Clear()	void	Clears all text from the control and resets the internal state.
TextUpdated (Event)	TextUpdatedEventArgs	Raised when the text changes, providing both the previous and new values for tracking and reacting to modifications.

Feature Description: This feature allows developers to retrieve, clear, and select text programmatically, facilitating enhanced control over text input, formatting, and event-driven text manipulation.

---

Key Points

Aspect	Detail
Raw Text Extraction	The GetRawPhoneNumber() method provides a clean version of the phone number with only digit characters, ideal for validation or storage.
Programmatic Selection	Methods such as Select(int, int) and SelectAll() enable precise control over which portion of the text is highlighted, useful for copy/cut operations or custom UI behaviors.
State Reset and Management	The Clear() method allows developers to reset the text content and related states (such as cursor position and selection) in a single call.
Event-Driven Updates	The TextUpdated event notifies subscribers whenever the text changes, enabling reactive programming patterns and synchronization with other UI components.

---

Best Practices

Practice	Explanation
Use GetRawPhoneNumber for Data Processing	Always retrieve the unformatted phone number when storing or validating the data, ensuring that formatting characters do not interfere.
Leverage Select and SelectAll for Enhanced UX	Programmatically select text to guide users during editing, for example, when a validation error occurs or when auto-filling data.
Call Clear() on Reset Scenarios	Use Clear() to reset the control in forms where users may need to start fresh, ensuring that internal state such as the cursor position is also reset.
Subscribe to TextUpdated for Synchronization	Use the TextUpdated event to trigger real-time validations or UI updates elsewhere in your application when the control’s text changes.

---

Common Pitfalls

Pitfall	How to Avoid
Neglecting Raw Data Extraction	Relying solely on the formatted text can lead to errors in validation or storage; always use GetRawPhoneNumber() when you need numeric data.
Overusing Programmatic Selection	Excessively calling Select() or SelectAll() can interfere with the natural user flow; use them judiciously and in response to clear user actions.
Improperly Resetting Text State	Ensure that Clear() is used when necessary so that residual selection or cursor positioning does not persist in unintended ways.
Ignoring TextUpdated Event	Failing to subscribe to TextUpdated may result in missed opportunities to synchronize state with other parts of the UI.

---

Usage Scenarios

Scenario	Example Use Case
Data Validation and Processing	Retrieve the raw phone number using GetRawPhoneNumber() for back-end validation or database storage, ensuring the absence of formatting characters.
Custom Text Selection Behavior	Use Select(int, int) to highlight a specific section of text automatically after input errors are detected, directing the user’s attention to that area.
Bulk Text Operations	Implement a “Clear” button in your form that calls Clear() to reset the phone number input field to its initial state.
Synchronizing UI on Text Change	Subscribe to the TextUpdated event to update labels, log changes, or trigger other actions whenever the phone number is modified.

---

Code Examples

Example 1: Retrieving the Raw Phone Number This sample demonstrates how to extract a phone number with only its numeric characters, suitable for further processing.

// Instantiate the control
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();
phoneNumberBox.Text = "[phone]";

// Retrieve the raw phone number (digits only)
string rawNumber = phoneNumberBox.GetRawPhoneNumber();
MessageBox.Show($"Raw Phone Number: {rawNumber}");
// Expected output: "15555555555"

Example 2: Programmatic Text Selection This sample shows how to select a portion of the text programmatically using the Select() method.

// Assume phoneNumberBox contains some text input
phoneNumberBox.Text = "15555555555";

// Programmatically select the area corresponding to the first three digits (for example, country code)
phoneNumberBox.Select(0, 3);

// Optionally, check the selection (e.g., for custom copy/cut operations)
string selectedText = phoneNumberBox.Text.Substring(0, 3);
MessageBox.Show($"Selected Text: {selectedText}");
// Expected output: "155"

Example 3: Clearing the Text Field This sample demonstrates how to clear the text input and reset the control’s state.

// Assume phoneNumberBox is being used in a form
phoneNumberBox.Text = "15555555555";

// Clear the text field
phoneNumberBox.Clear();

// Verify that the text has been cleared
if (string.IsNullOrEmpty(phoneNumberBox.Text))
{
    MessageBox.Show("The phone number field has been cleared.");
}

Example 4: Subscribing to the TextUpdated Event This sample illustrates how to subscribe to the TextUpdated event to monitor changes in the control’s text.

// Subscribe to the TextUpdated event to log changes
phoneNumberBox.TextUpdated += (sender, args) =>
{
    // args contains both the old and new text values
    Console.WriteLine($"Text changed from '{args.OldText}' to '{args.NewText}'.");
};

// Change the text to trigger the event
phoneNumberBox.Text = "[phone]";

---

Review

Aspect	Review Comment
Functional Versatility	The provided methods allow for robust text manipulation and retrieval, which is essential for tasks such as validation, formatting, and UI synchronization.
Ease of Integration	The straightforward API enables developers to easily integrate text manipulation features into their applications without complex workarounds.
Event-Driven Architecture	The TextUpdated event supports reactive programming models, ensuring that the UI remains in sync with text changes.

---

Summary

The Public Methods & Text Manipulation feature of the SiticonePhoneNumberBox control offers a versatile set of tools for managing text input. With methods to retrieve raw numbers, select text ranges, clear text, and respond to text updates, developers have full control over how the control’s text is processed and interacted with. These features facilitate seamless integration with application logic and improve overall data handling and user experience.

---

Additional Notes

Note Type	Detail
Extensibility	These text manipulation methods can be extended or combined with custom logic (e.g., custom undo/redo functionality) to further enhance usability.
Integration Tips	Consider coupling the TextUpdated event with other validation or UI update routines to maintain a responsive and consistent application interface.
Debugging	Log changes from the TextUpdated event during development to verify that text modifications are being captured as expected.