Text & Cursor Customization

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.

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.

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

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.

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.

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.