Back to Details

syncfusion-winforms-currency-textbox

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Windows Forms CurrencyTextBox

实现Syncfusion Windows Forms CurrencyTextBox

Syncfusion CurrencyTextBox is a specialized text input control derived from System.Windows.Forms.TextBox that provides currency-specific validation, formatting, and behavior. It handles keyboard input validation, culture-aware decimal formatting, and value constraints automatically.
Syncfusion CurrencyTextBox是派生自System.Windows.Forms.TextBox的专用文本输入控件，提供货币专属的校验、格式化及交互行为。它会自动处理键盘输入校验、适配区域文化的小数格式化，以及数值约束。

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
  • 创建带有自动校验功能的货币输入字段
  • 构建财务数据录入表单（发票、支付、预算）
  • 实现带正负值颜色区分的货币展示
  • 处理小数精度和千位分隔符
  • 处理货币数据的剪贴板操作
  • 添加数值倍数快捷键（Mega百万、Kilo千等）
  • 强制执行货币数值的上下限约束
  • 为大额数值显示溢出指示器

Component Overview

组件概述

The CurrencyTextBox control intercepts user keyboard input and prevents entry of invalid currency characters. It automatically formats the display based on decimal digits, group separators, and the currency symbol. Unlike the standard TextBox, it validates against min/max bounds and supports currency-specific events.
Key Capabilities:
  • 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
CurrencyTextBox控件会拦截用户的键盘输入，阻止输入无效的货币字符。它会根据小数位数、千位分隔符和货币符号自动格式化展示内容。与标准TextBox不同，它支持数值上下限校验，以及货币专属的事件。
核心功能：
  • 自动键盘输入校验
  • 适配区域文化的小数格式化
  • 可强制执行的最大/最小数值约束
  • 正值、负值、零值颜色区分
  • 剪贴板支持，可选择是否剥离格式
  • 带提示的溢出指示器
  • 数值倍数快捷键
  • 用于处理无效输入的ValidationError事件

Documentation Navigation Guide

文档导航指南

Getting Started

入门

📄 Read: references/getting-started.md
  • 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
📄 阅读：references/getting-started.md
  • 安装及程序集依赖
  • 创建项目并添加控件
  • 通过设计器或代码创建控件
  • 设置MaxValue/MinValue约束
  • 配置货币符号
  • 基础控件属性

Text Field Customization

文本字段自定义

📄 Read: references/text-field-customization.md
  • 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
📄 阅读：references/text-field-customization.md
  • 文本展示与对齐（左对齐、居中、右对齐）
  • 支持多行与自动换行
  • 密码字符掩码
  • 空状态提示文案
  • 数值与小数位格式化
  • 处理负值与负号
  • 空字符串配置

Value Formatting

数值格式化

📄 Read: references/value-formatting.md
  • 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
📄 阅读：references/value-formatting.md
  • 以程序方式访问DecimalValue
  • 货币符号自定义
  • 数值格式化（小数前总位数）
  • 小数位精度设置
  • 千位分隔符配置
  • 移除小数末尾的零
  • 货币正负值展示模式

Event Handling

事件处理

📄 Read: references/event-handling.md
  • 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
📄 阅读：references/event-handling.md
  • 用于处理快捷键的KeyDown事件
  • 添加倍数快捷键（G/M/K对应十亿/百万/千）
  • 处理无效输入的ValidationError事件
  • 基于StartPosition的错误信息处理
  • 使用ErrorProvider提供视觉反馈
  • 自定义校验场景

Appearance Customization

外观自定义

📄 Read: references/appearance-customization.md
  • 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
📄 阅读：references/appearance-customization.md
  • 边框样式（FixedSingle、Fixed3D、无）
  • 3D边框效果（凸起、凹陷、扁平等等）
  • 边框颜色与边框边配置
  • 按数值类型区分颜色（正值、负值、零值）
  • 只读状态背景色
  • 视觉样式应用

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • Clipboard support with formatting options
  • Overflow indicator display
  • Overflow indicator tooltips
  • Multiple clipboard modes
  • Data preservation strategies
📄 阅读：references/advanced-features.md
  • 带格式选项的剪贴板支持
  • 溢出指示器展示
  • 溢出指示器提示文案
  • 多种剪贴板模式
  • 数据保留策略

Validation and Constraints

校验与约束

📄 Read: references/validation-and-constraints.md
  • Setting min/max boundaries
  • Enforcing constraints during validation
  • Negative input behavior with selected text
  • AllowNull configuration
  • NullString custom display values
  • Value range enforcement
📄 阅读：references/validation-and-constraints.md
  • 设置数值上下限
  • 校验期间强制执行约束
  • 选中文本时的负值输入行为
  • AllowNull配置
  • NullString自定义展示值
  • 数值范围强制校验

Quick Start Example

快速入门示例

csharp
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);
    }
}
csharp
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

货币录入表单

csharp
// For collecting currency amounts (payments, invoices, etc.)
currencyTextBox.MaxValue = decimal.MaxValue;
currencyTextBox.MinValue = 0m;
currencyTextBox.CurrencySymbol = "$";
currencyTextBox.CurrencyDecimalDigits = 2;
currencyTextBox.AllowNull = false;
csharp
// 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

盈亏展示

csharp
// 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;
csharp
// 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

带占位符的可选金额

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

Keyboard Shortcuts for Large Numbers

大额数值快捷键

csharp
// 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;
    }
}
csharp
// 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 (十亿)
            currencyTextBox1.DecimalValue = value * 1000000000m;
            break;
        case Keys.M: // Mega (百万)
            currencyTextBox1.DecimalValue = value * 1000000m;
            break;
        case Keys.K: // Kilo (千)
            currencyTextBox1.DecimalValue = value * 1000m;
            break;
    }
}

Key Properties Reference

核心属性参考

PropertyTypePurposeCommon Values
DecimalValuedecimalGet/set numeric value programmaticallyAny valid decimal
CurrencySymbolstringCurrency symbol display"$", "€", "£", "¥"
CurrencyDecimalDigitsintDecimal places displayed2, 3, 4
CurrencyGroupSeparatorstringThousands separator",", ".", " "
MaxValuedecimalMaximum allowed value999999.99, 100000, etc.
MinValuedecimalMinimum allowed value0, -999999.99, etc.
PositiveColorColorColor for positive valuesColor.Black, Color.Green
NegativeColorColorColor for negative valuesColor.Red, Color.Maroon
ZeroColorColorColor for zero valueColor.Gray, Color.DarkGray
TextAlignHorizontalAlignmentText positionLeft, Center, Right
BorderStyleBorderStyleBorder appearanceFixedSingle, Fixed3D, None
AllowNullboolAllow empty/null valuestrue, false
ShowOverflowIndicatorboolShow indicator when value exceeds boundstrue, false
属性类型用途常用值
DecimalValuedecimal以程序方式读取/设置数值任意合法decimal值
CurrencySymbolstring展示的货币符号"$", "€", "£", "¥"
CurrencyDecimalDigitsint展示的小数位数2, 3, 4
CurrencyGroupSeparatorstring千位分隔符",", ".", " "
MaxValuedecimal允许的最大值999999.99, 100000等
MinValuedecimal允许的最小值0, -999999.99等
PositiveColorColor正值的展示颜色Color.Black, Color.Green
NegativeColorColor负值的展示颜色Color.Red, Color.Maroon
ZeroColorColor零值的展示颜色Color.Gray, Color.DarkGray
TextAlignHorizontalAlignment文本对齐方式左对齐, 居中, 右对齐
BorderStyleBorderStyle边框外观FixedSingle, Fixed3D, None
AllowNullbool是否允许空/Null值true, false
ShowOverflowIndicatorbool数值超出范围时是否展示指示器true, false

Use Cases by Scenario

场景化使用案例

Financial Application
  • Use positive/negative color coding
  • Set MaxValue to prevent data type overflow
  • Handle ValidationError for audit logging
  • Support clipboard for paste operations
Budget Entry Form
  • 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
Multi-Currency Display
  • Change CurrencySymbol based on user locale
  • Keep CurrencyDecimalDigits consistent (usually 2)
  • Adjust CurrencyGroupSeparator per region
  • Display DecimalValue consistently in database
Large Number Handling
  • 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
金融应用
  • 使用正负值颜色区分功能
  • 设置MaxValue防止数据类型溢出
  • 监听ValidationError事件用于审计日志
  • 支持剪贴板粘贴操作
预算录入表单
  • 设置合理的MaxValue（例如999999.99）
  • 按照数值使用习惯设置右对齐
  • 为必填项展示提示文案
  • 如果金额必须为正，设置MinValue为0
多货币展示
  • 根据用户区域设置切换CurrencySymbol
  • 保持CurrencyDecimalDigits一致（通常为2）
  • 按照区域调整CurrencyGroupSeparator
  • 在数据库中统一存储DecimalValue
大额数值处理
  • 开启数值倍数快捷键（G、M、K）
  • 当数值超出可见区域时使用ShowOverflowIndicator
  • 使用RemoveDecimalZeros属性移除小数末尾的零
  • 通过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
  • 选择匹配您需求的参考文档
  • 按照代码示例实现控件
  • 使用合法值与边界值进行测试
  • 监听ValidationError事件处理无效输入
  • 业务逻辑使用DecimalValue，展示使用Text属性