---
description: >-
  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.
---

# Public Methods & Text

## 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.

```csharp
// Instantiate the control
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();
phoneNumberBox.Text = "+1 (555) 555-5555";

// 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.

```csharp
// 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.

```csharp
// 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.

```csharp
// 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 = "+1 (555) 555-5555";
```

***

### 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.                        |









