Appearance Customization

This feature allows developers to adjust the visual presentation of the card number control—including borders, fill, corners, placeholder and cursor settings—to seamlessly integrate with their app UI.

Overview

The Appearance Customization feature exposes several public properties that let you control the look and feel of the SiticoneCardNumberBox. You can modify the border’s size, color, style, and gradient; set solid or gradient fills; define custom corner radii; configure placeholder animations; and tailor the cursor appearance. The following sections provide detailed guidance, code samples, and integration examples.

---

Property Details

The table below summarizes key properties associated with Appearance Customization.

Property	Description	Default Value/Notes
BorderSize	Sets the thickness of the control’s border.	1
BorderColor1	Primary border color when not focused or hovered.	Configurable; typically LightSlateGray
BorderColor2	Secondary border color (used for gradients).	Same as BorderColor1 by default
BorderFocusColor1	Primary border color when the control has focus.	Customizable (e.g., Blue tone)
BorderFocusColor2	Secondary border color for focused state.	Customizable
HoverBorderColor1	Primary border color when the control is hovered.	Customizable (e.g., Gray)
HoverBorderColor2	Secondary border color for hovered state.	Customizable
UseBorderGradient	Boolean to enable/disable border gradient.	false
BorderGradientMode	Direction of the border gradient (e.g., Horizontal, Vertical).	Horizontal by default
SolidFillColor	Sets the solid background fill color.	White
UseFillGradient	Boolean to enable/disable a gradient fill.	false
FillColor1	Primary fill color when using gradient fill.	White
FillColor2	Secondary fill color when using gradient fill.	White
FillGradientMode	Direction of the fill gradient (e.g., Horizontal, Vertical).	Horizontal by default
CornerRadiusTopLeft	Radius of the top-left corner.	0
CornerRadiusTopRight	Radius of the top-right corner.	0
CornerRadiusBottomLeft	Radius of the bottom-left corner.	0
CornerRadiusBottomRight	Radius of the bottom-right corner.	0
PlaceholderText	Text shown when no user input is present.	"Enter card number..." (example)
PlaceholderColor	Color of the placeholder text.	Gray
PlaceholderFadeInterval	Interval (in ms) for placeholder fade animation.	20
PlaceholderFadeStep	Step increment for placeholder fade (0.0 to 1.0).	0.05
CursorColor	Color of the blinking cursor.	Black
CursorWidth	Thickness of the cursor line.	1
CursorHeight	Height of the cursor.	26 or derived from Font.Height
CursorOffset	Horizontal offset for cursor positioning.	0
CursorStyle	Style/dash pattern for the cursor (using SiticoneDrawingStyle).	Solid by default

---

Code Examples

Example 1: Setting Up a Custom Border and Fill

Below is an example of how to set custom border and fill properties in your WinForms application:

// Create an instance of the SiticoneCardNumberBox control
SiticoneCardNumberBox cardNumberBox = new SiticoneCardNumberBox();

// Set border properties
cardNumberBox.BorderSize = 2;
cardNumberBox.BorderColor1 = Color.DarkGray;
cardNumberBox.BorderColor2 = Color.DarkGray;
cardNumberBox.BorderFocusColor1 = Color.Blue;
cardNumberBox.BorderFocusColor2 = Color.Blue;
cardNumberBox.UseBorderGradient = true;
cardNumberBox.BorderGradientMode = LinearGradientMode.Vertical;

// Set fill properties
cardNumberBox.SolidFillColor = Color.White;
cardNumberBox.UseFillGradient = true;
cardNumberBox.FillColor1 = Color.White;
cardNumberBox.FillColor2 = Color.LightBlue;
cardNumberBox.FillGradientMode = LinearGradientMode.Horizontal;

// Add the control to your form
this.Controls.Add(cardNumberBox);
cardNumberBox.Location = new Point(20, 20);
cardNumberBox.Size = new Size(300, 50);

Example 2: Customizing Corners and Placeholder Appearance

The following code demonstrates how to adjust corner radii and modify the placeholder settings:

// Create an instance of the control
SiticoneCardNumberBox cardNumberBox = new SiticoneCardNumberBox();

// Customize corner radii
cardNumberBox.CornerRadiusTopLeft = 10;
cardNumberBox.CornerRadiusTopRight = 10;
cardNumberBox.CornerRadiusBottomLeft = 5;
cardNumberBox.CornerRadiusBottomRight = 5;

// Customize placeholder settings
cardNumberBox.PlaceholderText = "Enter your card number here";
cardNumberBox.PlaceholderColor = Color.LightGray;
cardNumberBox.PlaceholderFadeInterval = 30;
cardNumberBox.PlaceholderFadeStep = 0.1;

// Add to form
this.Controls.Add(cardNumberBox);
cardNumberBox.Location = new Point(20, 80);
cardNumberBox.Size = new Size(300, 50);

Example 3: Customizing the Cursor

Customize the cursor appearance for a unique text entry feel:

SiticoneCardNumberBox cardNumberBox = new SiticoneCardNumberBox();

// Set cursor properties
cardNumberBox.CursorColor = Color.Red;
cardNumberBox.CursorWidth = 2;
cardNumberBox.CursorHeight = 30;
cardNumberBox.CursorOffset = 2;
cardNumberBox.CursorStyle = SiticoneDrawingStyle.Dash;

// Add to form
this.Controls.Add(cardNumberBox);
cardNumberBox.Location = new Point(20, 140);
cardNumberBox.Size = new Size(300, 50);

---

Key Points

The following table summarizes the key points for Appearance Customization:

Topic	Description
Border Customization	Modify thickness, color, gradient and style to match your UI.
Fill Customization	Choose solid or gradient backgrounds using defined color properties.
Corner Customization	Set individual corner radii for rounded control edges.
Placeholder & Cursor	Animate placeholder text and customize cursor attributes for clarity.

---

Best Practices

The table below outlines recommended practices when customizing appearance:

Best Practice	Explanation
Set both primary and secondary colors for gradients	Ensures a smooth visual gradient effect.
Use non-zero corner radii sparingly	Excessive rounding may affect the control's readability.
Test cursor visibility on different backgrounds	Guarantee proper contrast for better user experience.
Adjust placeholder fade settings for optimal timing	Creates a natural feel without distracting the user.

---

Common Pitfalls

The table below lists common pitfalls and how to avoid them:

Pitfall	How to Avoid It
Overlapping gradient and solid fill settings	Use one fill style at a time (solid or gradient).
Inconsistent border colors when switching states	Ensure focus and hover colors are distinct and tested.
Incorrect corner radii causing visual glitches	Test with different sizes and adjust gradually.
Misconfigured placeholder fade causing flicker	Fine-tune the fade interval and step for smooth transitions.

---

Usage Scenarios

The table below describes several scenarios where Appearance Customization is essential:

Scenario	Description
Theming an application	Match the control’s appearance with your application’s color scheme.
Accessibility adjustments	Increase border thickness and contrast for better readability.
Branding	Apply custom gradients and corner styles to align with brand identity.

---

Real Life Usage Scenarios

Scenario	Example
Financial application UI customization	Use a blue-focused border when a card field is active to guide user input.
Mobile banking application with dark/light modes	Toggle between different fill gradients to complement the system theme.
E-commerce checkout page with brand colors	Customize corners and border styles to mirror the company’s design language.

---

Troubleshooting Tips

Issue	Potential Cause	Recommended Action
Border does not appear as expected	Conflicting property values or gradient settings	Verify that UseBorderGradient is set appropriately and check color values.
Placeholder text flickers	Incorrect fade interval or step settings	Adjust PlaceholderFadeInterval and PlaceholderFadeStep values.
Cursor is not visible	CursorColor blending with background	Choose a contrasting CursorColor and test on different backgrounds.

---

Review

Aspect	Review Notes
Flexibility	The control provides extensive customization of appearance.
Integration	Properties are simple to set, allowing for quick integration.
User Experience	Customization options help enhance both aesthetics and usability.

---

Summary

The Appearance Customization feature of the SiticoneCardNumberBox control empowers developers to tailor the visual aspects of the card number input field. Through configurable border, fill, corner, placeholder, and cursor settings, you can achieve a seamless integration with your application’s design. Always test your appearance settings in different states (focused, hovered, read-only) and on various themes to ensure consistency and optimal user experience.

---

Additional Integration Example

Below is a complete integration example demonstrating multiple appearance customizations in one form:

public partial class MainForm : Form
{
    public MainForm()
    {
        InitializeComponent();
        InitializeCustomCardNumberBox();
    }

    private void InitializeCustomCardNumberBox()
    {
        // Create and configure the card number box
        SiticoneCardNumberBox cardNumberBox = new SiticoneCardNumberBox
        {
            Location = new Point(20, 20),
            Size = new Size(320, 50),
            BorderSize = 2,
            BorderColor1 = Color.DarkSlateGray,
            BorderColor2 = Color.DarkSlateGray,
            BorderFocusColor1 = Color.MediumBlue,
            BorderFocusColor2 = Color.MediumBlue,
            UseBorderGradient = true,
            BorderGradientMode = LinearGradientMode.Vertical,
            SolidFillColor = Color.WhiteSmoke,
            UseFillGradient = true,
            FillColor1 = Color.White,
            FillColor2 = Color.LightSteelBlue,
            FillGradientMode = LinearGradientMode.Horizontal,
            CornerRadiusTopLeft = 8,
            CornerRadiusTopRight = 8,
            CornerRadiusBottomLeft = 4,
            CornerRadiusBottomRight = 4,
            PlaceholderText = "Enter card number...",
            PlaceholderColor = Color.Gray,
            PlaceholderFadeInterval = 25,
            PlaceholderFadeStep = 0.08,
            CursorColor = Color.Black,
            CursorWidth = 1,
            CursorHeight = 28,
            CursorOffset = 2,
            CursorStyle = SiticoneDrawingStyle.Solid
        };

        // Add the customized control to the form
        this.Controls.Add(cardNumberBox);
    }
}

This example illustrates how to combine multiple appearance settings to produce a refined, professional look for the card number input control.

---

By following this documentation, developers can leverage the Appearance Customization feature to create controls that match their application's design standards while ensuring an excellent user experience.