Border and Background

This feature enables developers to customize the appearance of the control’s border and background, providing a variety of styling options such as solid or gradient colors, different states, etc.

Overview

The Visual Customization – Border & Background feature is governed by multiple public properties that allow developers to tailor the control’s look and feel. These properties control the base background color, border color in different states, gradient settings, and read-only appearances.

Property	Type	Default	Description
SolidFillColor	Color	White	Specifies the background fill color when gradients are not used.
SolidBorderColor	Color	LightSlateGray	Defines the border color in the normal (unfocused/unhovered) state.
SolidBorderFocusColor	Color	#4d4dff (converted from HTML)	Specifies the border color when the control is focused.
SolidBorderHoverColor	Color	Gray	Specifies the border color when the mouse is hovering over the control.
ShowBorder	bool	true	Toggles the display of the border around the control.
BorderColor1	Color	LightSlateGray	The starting color used for the border gradient when enabled.
BorderColor2	Color	LightSlateGray	The ending color for the border gradient when enabled.
UseBorderGradient	bool	false	Determines whether the border is rendered as a gradient rather than a single solid color.
BorderGradientMode	LinearGradientMode	Horizontal	Sets the direction for the border gradient.
BorderFocusColor1	Color	#4d4dff	The starting color for the border gradient in the focused state.
BorderFocusColor2	Color	#4d4dff	The ending color for the border gradient when focused.
HoverBorderColor1	Color	Gray	The starting color for the border gradient when the control is hovered over.
HoverBorderColor2	Color	Gray	The ending color for the border gradient when hovered over.
BorderSize	int	1	Specifies the thickness of the border.
ReadOnlyBorderColor1	Color	LightGray	Defines the border color for the control when it is in read-only mode.
ReadOnlyBorderColor2	Color	LightGray	The secondary border color for read-only mode when using gradients.
ReadOnlyFillColor1	Color	WhiteSmoke	The primary background color for the control in read-only mode.
ReadOnlyFillColor2	Color	WhiteSmoke	The secondary background color for read-only mode (used with gradients).
ReadOnlyPlaceholderColor	Color	DarkGray	The color used for the placeholder text when the control is read-only.

---

Key Points

Aspect	Detail
State-Specific Styling	The control supports different border and background colors for normal, focused, hovered, and read-only states.
Gradient Options	UseBorderGradient and related properties (BorderColor1, BorderColor2, BorderGradientMode) allow for a smooth gradient effect.
Read-Only Customization	Separate properties for read-only border and fill colors help maintain a distinct visual appearance when the control is not editable.

---

Best Practices

Practice	Explanation
Choose Complementary Colors	Select border and fill colors that align with your application’s theme for a consistent user interface.
Use Gradients Sparingly	While gradients can enhance the visual appeal, ensure that they do not detract from readability; test both gradient and solid options.
Adjust BorderSize Appropriately	Use a thicker border (higher BorderSize) if a bolder appearance is desired, but ensure it doesn’t overcrowd the control’s content.
Distinguish Focus and Hover States	Set distinct colors for SolidBorderFocusColor and SolidBorderHoverColor to provide clear visual feedback during interaction.
Configure Read-Only Appearance	Customize ReadOnlyBorderColor1/2 and ReadOnlyFillColor1/2 to indicate that the control is non-editable without compromising UI consistency.

---

Common Pitfalls

Pitfall	How to Avoid
Inconsistent State Colors	Ensure that colors for focused, hovered, and read-only states are coordinated to prevent jarring transitions.
Overuse of Gradients	Excessive use of gradient borders can lead to visual clutter; consider using a solid border for a simpler design if needed.
Manual Padding Interference	Avoid manually overriding the TextPadding settings when relying on automatic adjustments for the border and flag display.
Ignoring Read-Only Settings	If the control is set to read-only, ensure that the read-only properties (ReadOnlyBorderColor, ReadOnlyFillColor) are configured to clearly indicate the state.

---

Usage Scenarios

Scenario	Example Use Case
Standard Data Entry Form	Use a simple, solid border with a subtle background color to maintain clarity and focus in typical data entry scenarios.
Modern Application Interface	Implement a gradient border that changes on focus and hover to provide a dynamic and engaging user experience.
Read-Only Display Mode	Customize read-only border and fill colors to visually indicate that the control is non-editable while still matching the overall theme.

---

Code Examples

Example 1: Basic Solid Border and Background This sample configures the control to use a solid background and border without any gradient.

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

// Set the background and border for the normal state
phoneNumberBox.SolidFillColor = Color.White;
phoneNumberBox.SolidBorderColor = Color.LightSlateGray;
phoneNumberBox.SolidBorderFocusColor = ColorTranslator.FromHtml("#4d4dff");
phoneNumberBox.SolidBorderHoverColor = Color.Gray;
phoneNumberBox.ShowBorder = true;
phoneNumberBox.BorderSize = 1;

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

Example 2: Gradient Border Customization This sample demonstrates how to enable and configure a gradient border for a more modern look.

SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Enable border gradient and configure gradient colors
phoneNumberBox.UseBorderGradient = true;
phoneNumberBox.BorderColor1 = Color.LightSlateGray;
phoneNumberBox.BorderColor2 = Color.SlateBlue;
phoneNumberBox.BorderGradientMode = LinearGradientMode.Horizontal;

// Set specific gradient colors for the focused state
phoneNumberBox.BorderFocusColor1 = ColorTranslator.FromHtml("#4d4dff");
phoneNumberBox.BorderFocusColor2 = ColorTranslator.FromHtml("#4d4dff");

// Set gradient colors for hover state
phoneNumberBox.HoverBorderColor1 = Color.Gray;
phoneNumberBox.HoverBorderColor2 = Color.Gray;

// Set border thickness
phoneNumberBox.BorderSize = 1;

// Position and add the control
phoneNumberBox.Location = new Point(20, 80);
phoneNumberBox.Size = new Size(250, 40);
this.Controls.Add(phoneNumberBox);

Example 3: Configuring Read-Only Appearance This example shows how to customize the control’s appearance when it is set to read-only.

SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Set read-only properties to differentiate the appearance when not editable
phoneNumberBox.IsReadOnly = true;
phoneNumberBox.ReadOnlyBorderColor1 = Color.LightGray;
phoneNumberBox.ReadOnlyBorderColor2 = Color.LightGray;
phoneNumberBox.ReadOnlyFillColor1 = Color.WhiteSmoke;
phoneNumberBox.ReadOnlyFillColor2 = Color.WhiteSmoke;
phoneNumberBox.ReadOnlyPlaceholderColor = Color.DarkGray;

// Position and add the control
phoneNumberBox.Location = new Point(20, 140);
phoneNumberBox.Size = new Size(250, 40);
this.Controls.Add(phoneNumberBox);

---

Review

Aspect	Review Comment
Customizability	The control offers extensive customization options for both the border and background across various interaction states.
Visual Feedback	Differentiating colors for focus, hover, and read-only states provide clear user feedback, enhancing the overall UX.
Integration Flexibility	Developers can easily toggle between solid and gradient styles to match the desired aesthetic of their application.

---

Summary

The Visual Customization – Border & Background feature of the SiticonePhoneNumberBox control provides a robust set of options for styling the control’s outer appearance. With properties for solid and gradient borders, state-specific colors, and read-only customization, developers have the flexibility to create a polished and cohesive UI that fits their application’s theme.

---

Additional Notes

Note Type	Detail
Extensibility	The border and background properties can be combined with other visual features such as shadow effects and corner customization for a richer UI experience.
Integration Tips	Ensure that border and background colors, along with padding adjustments, are coordinated with adjacent controls to maintain a consistent design.
UI Consistency	Regularly test different states (normal, focused, hovered, read-only) to ensure that the visual appearance remains cohesive across interactions.