Implementing Syncfusion Windows Forms CurrencyTextBox

When to Use This Skill

• Creating currency input fields with automatic validation
• Building financial data entry forms (invoices, payments, budgets)
• Implementing currency display with positive/negative color coding
• Working with decimal precision and grouping separators
• Handling clipboard operations with currency data
• Adding keyboard shortcuts for multiplying values (Mega, Kilo, etc.)
• Enforcing minimum and maximum currency values
• Displaying overflow indicators for large numbers

Component Overview

• Automatic keyboard input validation
• Culture-aware decimal formatting
• Max/Min value constraints with enforcement
• Positive, negative, and zero value color coding
• Clipboard support with optional format stripping
• Overflow indicators with tooltips
• Keyboard shortcuts for multiplying values
• ValidationError event for invalid input handling

Documentation Navigation Guide

Getting Started

• Installation and assembly dependencies
• Creating a project and adding the control
• Designer and code-based control creation
• Setting up MaxValue/MinValue constraints
• Configuring currency symbols
• Basic control properties

Text Field Customization

• Text display and alignment (Left, Center, Right)
• Multiline support with word wrapping
• Password character masking
• Banner text for empty state
• Number and decimal digit formatting
• Handling negative values and signs
• Null string configuration

Value Formatting

• DecimalValue programmatic access
• Currency symbol customization
• Number formatting (total digits before decimal)
• Decimal digit precision
• Group separator configuration
• Removing trailing decimal zeros
• Currency positive and negative patterns

Event Handling

• KeyDown event for keyboard shortcuts
• Adding multiplier keys (G, M, K for Giga/Mega/Kilo)
• ValidationError event for invalid input
• Error message handling with StartPosition
• Using ErrorProvider for visual feedback
• Custom validation scenarios

Appearance Customization

• Border styles (FixedSingle, Fixed3D, None)
• 3D border effects (Raised, Sunken, Flat, etc.)
• Border color and side configuration
• Color coding by value (Positive, Negative, Zero)
• ReadOnly background color
• Visual style application

Advanced Features

• Clipboard support with formatting options
• Overflow indicator display
• Overflow indicator tooltips
• Multiple clipboard modes
• Data preservation strategies

Validation and Constraints

• Setting min/max boundaries
• Enforcing constraints during validation
• Negative input behavior with selected text
• AllowNull configuration
• NullString custom display values
• Value range enforcement

Quick Start Example

using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

public partial class Form1 : Form
{
    private CurrencyTextBox currencyTextBox1;
    
    public Form1()
    {
        InitializeComponent();
        
        // Create and configure CurrencyTextBox
        currencyTextBox1 = new CurrencyTextBox();
        currencyTextBox1.Location = new System.Drawing.Point(10, 10);
        currencyTextBox1.Size = new System.Drawing.Size(200, 25);
        
        // Set currency format
        currencyTextBox1.CurrencySymbol = "$";
        currencyTextBox1.CurrencyDecimalDigits = 2;
        currencyTextBox1.CurrencyGroupSeparator = ",";
        currencyTextBox1.CurrencyGroupSizes = new int[] { 3 };
        
        // Set value constraints
        currencyTextBox1.MaxValue = 999999.99m;
        currencyTextBox1.MinValue = 0m;
        currencyTextBox1.DecimalValue = 100.00m;
        
        // Set colors for value states
        currencyTextBox1.PositiveColor = System.Drawing.Color.Black;
        currencyTextBox1.NegativeColor = System.Drawing.Color.Red;
        currencyTextBox1.ZeroColor = System.Drawing.Color.Gray;
        
        this.Controls.Add(currencyTextBox1);
    }
}

Common Patterns

Currency Entry Form

// For collecting currency amounts (payments, invoices, etc.)
currencyTextBox.MaxValue = decimal.MaxValue;
currencyTextBox.MinValue = 0m;
currencyTextBox.CurrencySymbol = "$";
currencyTextBox.CurrencyDecimalDigits = 2;
currencyTextBox.AllowNull = false;

Profit/Loss Display

// Color-code by sign (green for profit, red for loss)
currencyTextBox.PositiveColor = System.Drawing.Color.Green;
currencyTextBox.NegativeColor = System.Drawing.Color.Red;
currencyTextBox.MaxValue = decimal.MaxValue;
currencyTextBox.MinValue = decimal.MinValue;

Optional Amount with Placeholder

// Allow null values with custom placeholder text
currencyTextBox.AllowNull = true;
currencyTextBox.NullString = "(Not Specified)";
currencyTextBox.Text = "";

Keyboard Shortcuts for Large Numbers

// Handle KeyDown event to add multiplier shortcuts
private void currencyTextBox1_KeyDown(object sender, KeyEventArgs e)
{
    decimal value = currencyTextBox1.DecimalValue;
    switch(e.KeyCode)
    {
        case Keys.G: // Giga (billion)
            currencyTextBox1.DecimalValue = value * 1000000000m;
            break;
        case Keys.M: // Mega (million)
            currencyTextBox1.DecimalValue = value * 1000000m;
            break;
        case Keys.K: // Kilo (thousand)
            currencyTextBox1.DecimalValue = value * 1000m;
            break;
    }
}

Key Properties Reference

Use Cases by Scenario

• Use positive/negative color coding
• Set MaxValue to prevent data type overflow
• Handle ValidationError for audit logging
• Support clipboard for paste operations

• Set reasonable MaxValue (e.g., 999999.99)
• Use TextAlign.Right for numeric convention
• Display banner text for required fields
• Enforce MinValue of 0 if amounts must be positive

• Change CurrencySymbol based on user locale
• Keep CurrencyDecimalDigits consistent (usually 2)
• Adjust CurrencyGroupSeparator per region
• Display DecimalValue consistently in database

• Enable keyboard multiplier shortcuts (G, M, K)
• Use ShowOverflowIndicator for values exceeding visible space
• Remove decimal zeros with RemoveDecimalZeros property
• Increase number digits with CurrencyNumberDigits

Next Steps

• Choose the reference file matching your task
• Implement the control following the code examples
• Test with both valid and edge-case values
• Handle ValidationError event for invalid input
• Use DecimalValue for business logic, Text for display