Phone Number Config

This feature enables developers to customize the formatting and behavior of phone number input by controlling country settings, formatting rules, display options, etc.

Overview

The Phone Number Configuration feature encompasses the following public properties and settings that determine the formatting and validation of phone numbers:

Property	Type	Default	Description
SelectedCountry	Country (enum)	UnitedStates	Sets the country used for formatting, which influences the country code and flag display.
ISOCountryCode	string	"us"	Sets the two-letter ISO country code (e.g., "us", "gb") to determine the flag image and country-specific behavior.
CountryCode	string	"1"	Specifies the dialing code prefix (without the "+" sign) for the phone number.
AllowInternational	bool	true	Enables or disables the ability to enter international phone numbers.
AutoFormatting	bool	true	Automatically formats the phone number as it is typed, based on the selected country and formatting rules.
RequireCountryCode	bool	true	Determines whether the country code is required as part of the phone number.
PhoneFormat	PhoneNumberFormat (enum)	International	Specifies the display format of the phone number (e.g., International, National, Basic).

---

Key Points

The following table highlights the important aspects of this feature:

Aspect	Detail
Country Setting	The SelectedCountry, ISOCountryCode, and CountryCode properties work together to set the dialing and formatting information.
Input Formatting	AutoFormatting ensures that as a user types, the control reformats the input according to the set PhoneFormat.
Validation	The combination of AllowInternational and RequireCountryCode governs whether the input adheres to international or local formats.
Display Customization	PhoneFormat directly influences the appearance of the placeholder text and input mask.

---

Best Practices

It is recommended to follow these practices when using the Phone Number Configuration feature:

Practice	Explanation
Set the SelectedCountry and ISOCountryCode	Always update both properties to ensure that the correct flag and formatting settings are applied.
Enable AutoFormatting	This provides immediate visual feedback to users and ensures consistency in phone number appearance.
Validate Country Code	Use the RequireCountryCode setting if you need to ensure that a country code is always present.
Test Different PhoneFormat Values	Verify how each PhoneFormat (International, National, Basic) affects the placeholder and formatting.

---

Common Pitfalls

Below is a table summarizing common mistakes and how to avoid them:

Pitfall	How to Avoid
Inconsistent country and country code values	Ensure that when setting CountryCode, the corresponding ISOCountryCode is updated appropriately.
Overriding AutoFormatting unintentionally	Do not disable AutoFormatting unless you intend to implement custom formatting logic.
Ignoring RequireCountryCode	If the control requires a country code, ensure RequireCountryCode is set to true to avoid invalid inputs.
Using an unsupported PhoneFormat value	Stick to the defined enum values (International, National, Basic) to ensure predictable behavior.

---

Usage Scenarios

This feature can be applied in several scenarios, as illustrated in the table below:

Scenario	Example Use Case
Global Application	Use SelectedCountry and AllowInternational to support users from multiple regions with correct dialing formats.
Local Phone Input	Set PhoneFormat to National and RequireCountryCode to false if only local numbers should be accepted.
Dynamic Country Switching	Update ISOCountryCode and CountryCode at runtime when the user selects a different country from a list.

---

Code Examples

Below are some code examples that demonstrate how to integrate and configure the Phone Number Configuration feature in your WinForms application:

Example 1: Basic Setup This sample demonstrates setting up the control for an international phone number with automatic formatting enabled.

// Create a new instance of the phone number box control
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Configure the phone number settings
phoneNumberBox.SelectedCountry = Country.UnitedStates;
phoneNumberBox.ISOCountryCode = "us";
phoneNumberBox.CountryCode = "1";
phoneNumberBox.AllowInternational = true;
phoneNumberBox.AutoFormatting = true;
phoneNumberBox.RequireCountryCode = true;
phoneNumberBox.PhoneFormat = PhoneNumberFormat.International;

// Set location and size for integration in the form
phoneNumberBox.Location = new Point(20, 20);
phoneNumberBox.Size = new Size(250, 40);

// Add the control to the form
this.Controls.Add(phoneNumberBox);

Example 2: Local Phone Number Input This sample shows how to configure the control for local phone numbers without a required country code.

SiticonePhoneNumberBox localPhoneBox = new SiticonePhoneNumberBox();

// Configure for local phone numbers (e.g., national format)
localPhoneBox.SelectedCountry = Country.UnitedStates;
localPhoneBox.ISOCountryCode = "us";
localPhoneBox.CountryCode = "1";
localPhoneBox.AllowInternational = false;
localPhoneBox.AutoFormatting = true;
localPhoneBox.RequireCountryCode = false;
localPhoneBox.PhoneFormat = PhoneNumberFormat.National;

// Set additional UI properties
localPhoneBox.Location = new Point(20, 80);
localPhoneBox.Size = new Size(250, 40);

// Add to form
this.Controls.Add(localPhoneBox);

Example 3: Changing Phone Format at Runtime Demonstrates how to switch the phone number format dynamically based on user selection.

// Assume phoneNumberBox is already created and added to the form
void OnFormatChanged(object sender, EventArgs e)
{
    // Change the phone number format based on some user input (e.g., a ComboBox selection)
    switch (comboBoxFormat.SelectedItem.ToString())
    {
        case "International":
            phoneNumberBox.PhoneFormat = PhoneNumberFormat.International;
            break;
        case "National":
            phoneNumberBox.PhoneFormat = PhoneNumberFormat.National;
            break;
        case "Basic":
            phoneNumberBox.PhoneFormat = PhoneNumberFormat.Basic;
            break;
    }
}

---

Review

Aspect	Review Comment
Configuration Flexibility	The properties provide granular control over how phone numbers are input and displayed.
Integration Simplicity	Code examples demonstrate straightforward instantiation and property configuration.
Dynamic Behavior	The control automatically updates formatting and flag display based on the configured settings.

---

Summary

The Phone Number Configuration feature of the SiticonePhoneNumberBox control allows you to customize phone number input through country-specific settings, automatic formatting, and display options. This ensures that users have a consistent and localized input experience. By following best practices and leveraging the provided properties, you can easily integrate this control into global or local applications.

---

Additional Notes

Note Type	Detail
Extensibility	Developers can further extend behavior by subscribing to events such as TextUpdated and Validated.
Custom Validation	In combination with the ValidationFunction property, additional business rules can be enforced.
UI Consistency	Ensure that visual settings (e.g., placeholder text and auto-formatting) match the overall application theme.