---
description: >-
  This feature enables developers to control the appearance and behavior of the
  text displayed in the control as well as the look and feel of the cursor,
  ensuring that user input is both legible, etc.
---

# Text & Cursor Customization

## Overview

The Text & Cursor Customization feature is managed via several public properties that affect text alignment, transformation, styling (such as bold or italic), selection colors, and detailed cursor properties (blink rate, color, width, height, offset, and style). These settings allow developers to fine-tune both the presentation of user-entered text and the interactive cursor that indicates the insertion point.

| Property              | Type                        | Default                               | Description                                                                                         |
| --------------------- | --------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- |
| TextAlign             | TextAlignment (enum)        | Left                                  | Sets the horizontal alignment of the input text (Left, Center, or Right).                           |
| UseSystemPasswordChar | bool                        | false                                 | When true, masks the displayed text using the specified PasswordChar for privacy.                   |
| PasswordChar          | char                        | '●'                                   | The character used to mask the text when UseSystemPasswordChar is enabled.                          |
| TextCaseMode          | TextCase (enum)             | Normal                                | Transforms the text to a specific case: Normal (as typed), Upper, or Lower.                         |
| IsBold                | bool                        | false                                 | When set to true, displays the text in bold font.                                                   |
| IsItalic              | bool                        | false                                 | When set to true, displays the text in italic font.                                                 |
| IsUnderline           | bool                        | false                                 | When set to true, underlines the text.                                                              |
| IsStrikeThrough       | bool                        | false                                 | When set to true, draws a strike-through line over the text.                                        |
| SelectionBackColor    | Color                       | (Default system highlight color)      | Specifies the background color for the selected text.                                               |
| SelectionForeColor    | Color                       | (Default system highlight text color) | Specifies the text color for the selected text.                                                     |
| SelectionHeight       | int                         | 0                                     | Determines the vertical height of the text selection highlight.                                     |
| CursorBlinkRate       | int                         | 500                                   | Controls the blink rate (in milliseconds) of the cursor.                                            |
| CursorColor           | Color                       | Black                                 | Sets the color of the cursor used to indicate the text insertion point.                             |
| CursorWidth           | int                         | 1                                     | Specifies the thickness of the cursor.                                                              |
| CursorHeight          | int                         | 26                                    | Sets the height of the cursor, typically matching the font size or control height.                  |
| CursorOffset          | int                         | 0                                     | Adjusts the horizontal offset of the cursor relative to the text start position.                    |
| CursorStyle           | SiticoneDrawingStyle (enum) | Solid                                 | Defines the visual style of the cursor (for example, solid or dashed) for additional customization. |

***

### Key Points

| Aspect                            | Detail                                                                                                                                               |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text Alignment and Transformation | TextAlign, TextCaseMode, and font style toggles (IsBold, IsItalic, etc.) allow for a wide range of text display customizations.                      |
| Password Mode                     | UseSystemPasswordChar and PasswordChar provide a secure way to mask sensitive input while still displaying a consistent visual style.                |
| Selection Appearance              | SelectionBackColor, SelectionForeColor, and SelectionHeight let developers clearly define how selected text appears.                                 |
| Cursor Customization              | CursorBlinkRate, CursorColor, CursorWidth, CursorHeight, CursorOffset, and CursorStyle provide granular control over cursor appearance and behavior. |

***

### Best Practices

| Practice                                      | Explanation                                                                                                                                     |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Consistent Text Styling                       | Use the font style properties (IsBold, IsItalic, IsUnderline, IsStrikeThrough) consistently across your application to maintain a uniform look. |
| Adjust Cursor Parameters to Enhance Usability | Choose a CursorBlinkRate and CursorWidth that are easily visible but not distracting, ensuring the cursor remains prominent for users.          |
| Use Password Mode Only When Necessary         | Enable UseSystemPasswordChar only for sensitive fields to avoid unnecessary masking of regular input.                                           |
| Test Text Alignment and Transformation        | Verify that TextAlign and TextCaseMode produce the expected result on various input lengths and across different system cultures.               |
| Match Selection Colors with Application Theme | Select SelectionBackColor and SelectionForeColor that complement the overall UI to provide clear visual feedback during text selection.         |

***

### Common Pitfalls

| Pitfall                                   | How to Avoid                                                                                                                              |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Inconsistent Font Styling Across Controls | Ensure that text style properties (bold, italic, underline, strike-through) are standardized across similar input controls.               |
| Overly Fast or Slow Cursor Blink Rate     | Adjust the CursorBlinkRate based on user testing; a blink rate that is too fast can be distracting, while too slow may not be noticeable. |
| Poor Contrast in Selection Colors         | Verify that the chosen SelectionBackColor and SelectionForeColor provide adequate contrast for readability in all lighting conditions.    |
| Improper Handling of Password Masking     | When using UseSystemPasswordChar, ensure that the PasswordChar is clearly visible and consistent across the application.                  |

***

### Usage Scenarios

| Scenario                          | Example Use Case                                                                                                                           |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Secure Input Fields               | Enable UseSystemPasswordChar for password fields so that sensitive data is masked, using a consistent PasswordChar (e.g., '●').            |
| Data Entry with Custom Formatting | Use TextAlign and TextCaseMode to ensure that all phone numbers are displayed in a standardized format (e.g., all uppercase or centered).  |
| Enhanced Visual Feedback          | Customize selection colors and cursor properties to match the application’s theme, thereby improving user interaction during text editing. |
| Emphasizing User Interaction      | Use font styling toggles (IsBold, IsItalic) and a distinctive cursor style to make interactive fields more engaging and noticeable.        |

***

### Code Examples

Example 1: Basic Text Customization\
This example demonstrates how to configure text alignment, case transformation, and font styling.

```csharp
// Instantiate the control
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Set text alignment and case
phoneNumberBox.TextAlign = TextAlignment.Center;
phoneNumberBox.TextCaseMode = TextCase.Upper;

// Enable font styling (bold and italic)
phoneNumberBox.IsBold = true;
phoneNumberBox.IsItalic = true;

// Set location and size
phoneNumberBox.Location = new Point(20, 20);
phoneNumberBox.Size = new Size(250, 40);

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

Example 2: Configuring Password Mode\
This example shows how to enable password masking with a custom masking character.

```csharp
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Enable password mode to mask input
phoneNumberBox.UseSystemPasswordChar = true;
phoneNumberBox.PasswordChar = '*';

// Optionally, adjust text alignment for password entry
phoneNumberBox.TextAlign = TextAlignment.Left;

// Set location and add to the form
phoneNumberBox.Location = new Point(20, 80);
phoneNumberBox.Size = new Size(250, 40);
this.Controls.Add(phoneNumberBox);
```

Example 3: Customizing Cursor Appearance\
This sample demonstrates how to adjust cursor properties such as blink rate, color, width, height, and offset.

```csharp
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Configure cursor properties
phoneNumberBox.CursorBlinkRate = 500;       // Cursor blinks every 500 milliseconds
phoneNumberBox.CursorColor = Color.Red;       // Set the cursor color to red for high visibility
phoneNumberBox.CursorWidth = 2;               // Make the cursor thicker than the default
phoneNumberBox.CursorHeight = 30;             // Adjust the cursor height to better match the control
phoneNumberBox.CursorOffset = 2;              // Slightly offset the cursor for improved readability
phoneNumberBox.CursorStyle = SiticoneDrawingStyle.Dashed; // Use a dashed style for the cursor

// Set location and size
phoneNumberBox.Location = new Point(20, 140);
phoneNumberBox.Size = new Size(250, 40);
this.Controls.Add(phoneNumberBox);
```

Example 4: Customizing Text Selection Appearance\
This example shows how to set the colors and height of the text selection.

```csharp
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Configure selection appearance
phoneNumberBox.SelectionBackColor = Color.LightBlue;
phoneNumberBox.SelectionForeColor = Color.DarkBlue;
phoneNumberBox.SelectionHeight = 20;  // Sets a custom selection highlight height

// Set location and add to the form
phoneNumberBox.Location = new Point(20, 200);
phoneNumberBox.Size = new Size(250, 40);
this.Controls.Add(phoneNumberBox);
```

***

### Review

| Aspect                     | Review Comment                                                                                                                                 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Customization Flexibility  | The feature provides extensive options to control text appearance, from alignment and case transformation to font styles and selection colors. |
| Responsive Cursor Behavior | Detailed cursor customization (blink rate, style, offset) enhances user feedback during text entry.                                            |
| Integration Simplicity     | Code examples demonstrate straightforward integration and configuration, making it easy to tailor the control to application design needs.     |

***

### Summary

The Text & Cursor Customization feature of the SiticonePhoneNumberBox control offers comprehensive options to manage how text is displayed and how the cursor behaves. By configuring properties such as text alignment, case, font styles, selection colors, and detailed cursor settings, developers can create a polished input experience that aligns with their application’s overall design and usability requirements.

***

### Additional Notes

| Note Type        | Detail                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Extensibility    | Text transformation and styling properties can be extended or dynamically changed at runtime to react to user preferences or system themes. |
| Integration Tips | Coordinate text and cursor customization with other UI elements (e.g., borders and backgrounds) to maintain visual consistency.             |
| Debugging        | Monitor real-time changes to text and cursor properties during development to ensure that visual feedback matches expected behavior.        |







