syncfusion-winforms-integer-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Windows Forms Integer TextBox

Syncfusion Windows Forms Integer TextBox控件实现指南

When to Use This Skill

适用场景

Use this skill when you need to:

Create numeric input fields that accept only integer values
Set up value constraints (minimum and maximum bounds)
Format and display numbers with custom separators
Handle negative values and validation
Respond to value changes and validation errors in Windows Forms applications
Apply visual styling to numeric inputs (colors, borders)

当你需要以下功能时可使用本指南：

创建仅接受整数值的数值输入字段
设置值约束（最小和最大边界）
使用自定义分隔符格式化和显示数字
处理负值和验证
在Windows Forms应用中响应值变化和验证错误
为数值输入应用视觉样式（颜色、边框）

Component Overview

组件概述

The IntegerTextBox is a specialized Windows Forms control derived from the standard TextBox. It:

Accepts and displays only integer data types
Enforces min/max value constraints automatically
Supports custom number formatting with group separators
Provides events for value changes and validation errors
Allows visual customization through colors and styling
Handles null values and read-only states
Supports leading zeros and negative value handling

Key Characteristics:

Restricts input to integer values only
Validates input in real-time
Provides wrapper properties for null handling
Offers formatting options without themes or localization
Lightweight and responsive to user interactions

IntegerTextBox是从标准TextBox派生的专用Windows Forms控件，它：

仅接受和显示整数数据类型
自动强制执行最小/最大值约束
支持带分组分隔符的自定义数字格式化
提供值变化和验证错误的事件
允许通过颜色和样式进行视觉自定义
处理空值和只读状态
支持前导零和负值处理

关键特性：

仅限制输入整数值
实时验证输入
提供用于空值处理的包装属性
无需主题或本地化即可提供格式化选项
轻量且响应用户交互

Documentation & Navigation Guide

文档与导航指南

Choose the reference that matches your current task:

选择与当前任务匹配的参考文档：

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and NuGet package setup
Adding control through designer
Adding control manually in C# code
Setting minimum and maximum value constraints
Initial configuration patterns

📄 阅读： references/getting-started.md

安装和NuGet包设置
通过设计器添加控件
在C#代码中手动添加控件
设置最小和最大值约束
初始配置模式

Visual Appearance

视觉外观

📄 Read: references/appearance.md

Setting background colors
Configuring text colors by value type (positive/negative/zero)
Border styling
Read-only state appearance
Color reset methods

📄 阅读： references/appearance.md

设置背景颜色
按值类型（正/负/零）配置文本颜色
边框样式
只读状态外观
颜色重置方法

Data Handling & Formatting

数据处理与格式化

📄 Read: references/data-formatting.md

Number formatting options
Group separators and group sizes
Handling negative values and key inputs
Leading zeros support
Null value management
Read-only with separate colors

📄 阅读： references/data-formatting.md

数字格式化选项
分组分隔符和分组大小
处理负值和按键输入
前导零支持
空值管理
带独立颜色的只读模式

Events & Interactions

事件与交互

📄 Read: references/events.md

BindableValueChanged event usage
IntegerValueChanged event handling
ValidationError event patterns
FormattedTextChanged and ClipTextChanged
Event handler implementation examples

📄 阅读： references/events.md

BindableValueChanged事件用法
IntegerValueChanged事件处理
ValidationError事件模式
FormattedTextChanged和ClipTextChanged
事件处理程序实现示例

Quick Start Example

快速入门示例

Here's a minimal working example:

csharp

using Syncfusion.Windows.Forms.Tools;

// Add assembly reference: Syncfusion.Shared.Base
// Include namespace: Syncfusion.Windows.Forms.Tools

// Create and add control
IntegerTextBox integerTextBox1 = new IntegerTextBox();
this.Controls.Add(integerTextBox1);

// Set constraints
integerTextBox1.MaxValue = 999999;
integerTextBox1.MinValue = -999999;
integerTextBox1.IntegerValue = 0;

以下是一个最简运行示例：

csharp

using Syncfusion.Windows.Forms.Tools;

// Add assembly reference: Syncfusion.Shared.Base
// Include namespace: Syncfusion.Windows.Forms.Tools

// Create and add control
IntegerTextBox integerTextBox1 = new IntegerTextBox();
this.Controls.Add(integerTextBox1);

// Set constraints
integerTextBox1.MaxValue = 999999;
integerTextBox1.MinValue = -999999;
integerTextBox1.IntegerValue = 0;

Common Patterns

常见模式

Pattern 1: Value-Based Color Coding

模式1：基于值的颜色编码

Display positive values in green, negative in red, zero in gray:

csharp

integerTextBox1.PositiveColor = System.Drawing.Color.Green;
integerTextBox1.NegativeColor = System.Drawing.Color.Red;
integerTextBox1.ZeroColor = System.Drawing.Color.Gray;

将正值显示为绿色，负值显示为红色，零显示为灰色：

csharp

integerTextBox1.PositiveColor = System.Drawing.Color.Green;
integerTextBox1.NegativeColor = System.Drawing.Color.Red;
integerTextBox1.ZeroColor = System.Drawing.Color.Gray;

Pattern 2: Number Formatting with Separators

模式2：带分隔符的数字格式化

Format large numbers with custom separators (e.g., "1,234,567"):

csharp

integerTextBox1.NumberGroupSeparator = ",";
integerTextBox1.NumberGroupSizes = new int[] { 3 };
integerTextBox1.IntegerValue = 1234567;

使用自定义分隔符格式化大数字（例如“1,234,567”）：

csharp

integerTextBox1.NumberGroupSeparator = ",";
integerTextBox1.NumberGroupSizes = new int[] { 3 };
integerTextBox1.IntegerValue = 1234567;

Pattern 3: Handling Value Changes

模式3：处理值变化

Respond when the user enters a new value:

csharp

integerTextBox1.BindableValueChanged += 
    (sender, e) => MessageBox.Show($"New value: {integerTextBox1.IntegerValue}");

响应用户输入新值的情况：

csharp

integerTextBox1.BindableValueChanged += 
    (sender, e) => MessageBox.Show($"New value: {integerTextBox1.IntegerValue}");

Pattern 4: Validation with Error Handling

模式4：带错误处理的验证

Catch and respond to validation errors:

csharp

integerTextBox1.ValidationError += (sender, e) =>
{
    MessageBox.Show("Invalid input! Please enter a valid integer.");
};

捕获并响应验证错误：

csharp

integerTextBox1.ValidationError += (sender, e) =>
{
    MessageBox.Show("Invalid input! Please enter a valid integer.");
};

Key Properties

关键属性

Property	Purpose	Example
MaxValue	Upper bound for integer values	`integerTextBox1.MaxValue = 100;`
MinValue	Lower bound for integer values	`integerTextBox1.MinValue = 0;`
IntegerValue	Get/set the current integer value	`int val = integerTextBox1.IntegerValue;`
BindableValue	Wrapper for null-safe value access	`integerTextBox1.BindableValue = null;`
AllowLeadingZeros	Allow zeros before number (e.g., "0123")	`integerTextBox1.AllowLeadingZeros = true;`
NumberGroupSeparator	Character to separate digit groups	`integerTextBox1.NumberGroupSeparator = ",";`
NumberGroupSizes	Size of each digit group	`integerTextBox1.NumberGroupSizes = new int[] { 3 };`
PositiveColor	Color for positive values	`integerTextBox1.PositiveColor = Color.Green;`
NegativeColor	Color for negative values	`integerTextBox1.NegativeColor = Color.Red;`
ZeroColor	Color when value is zero	`integerTextBox1.ZeroColor = Color.Gray;`
BackColor	Control background color	`integerTextBox1.BackColor = Color.White;`
ReadOnlyBackColor	Background when read-only	`integerTextBox1.ReadOnlyBackColor = Color.LightGray;`
ReadOnly	Prevent user editing	`integerTextBox1.ReadOnly = true;`
DeleteSelectionOnNegative	Delete selected text when minus pressed	`integerTextBox1.DeleteSelectionOnNegative = true;`

属性	用途	示例
MaxValue	整数值的上限	`integerTextBox1.MaxValue = 100;`
MinValue	整数值的下限	`integerTextBox1.MinValue = 0;`
IntegerValue	获取/设置当前整数值	`int val = integerTextBox1.IntegerValue;`
BindableValue	用于空值安全访问的包装器	`integerTextBox1.BindableValue = null;`
AllowLeadingZeros	允许数字前加零（例如“0123”）	`integerTextBox1.AllowLeadingZeros = true;`
NumberGroupSeparator	用于分隔数字组的字符	`integerTextBox1.NumberGroupSeparator = ",";`
NumberGroupSizes	每个数字组的大小	`integerTextBox1.NumberGroupSizes = new int[] { 3 };`
PositiveColor	正值的颜色	`integerTextBox1.PositiveColor = Color.Green;`
NegativeColor	负值的颜色	`integerTextBox1.NegativeColor = Color.Red;`
ZeroColor	值为零时的颜色	`integerTextBox1.ZeroColor = Color.Gray;`
BackColor	控件背景颜色	`integerTextBox1.BackColor = Color.White;`
ReadOnlyBackColor	只读状态下的背景色	`integerTextBox1.ReadOnlyBackColor = Color.LightGray;`
ReadOnly	阻止用户编辑	`integerTextBox1.ReadOnly = true;`
DeleteSelectionOnNegative	按下减号时删除选中的文本	`integerTextBox1.DeleteSelectionOnNegative = true;`

Common Use Cases

常见用例

Use Case 1: Financial Input with Constraints Create a textbox for dollar amounts (0 to 999,999):

csharp

integerTextBox1.MinValue = 0;
integerTextBox1.MaxValue = 999999;
integerTextBox1.NumberGroupSeparator = ",";
integerTextBox1.NumberGroupSizes = new int[] { 3 };

Use Case 2: Temperature Input (Negative & Positive) Allow temperatures from -50 to 50 degrees:

csharp

integerTextBox1.MinValue = -50;
integerTextBox1.MaxValue = 50;
integerTextBox1.NegativeColor = Color.Blue;
integerTextBox1.PositiveColor = Color.Red;

Use Case 3: Read-Only Display Show a value that users cannot modify:

csharp

integerTextBox1.IntegerValue = 42;
integerTextBox1.ReadOnly = true;
integerTextBox1.ReadOnlyBackColor = Color.LightGray;

Use Case 4: Null-Able Integer with Validation Allow null values with error handling:

csharp

integerTextBox1.BindableValueChanged += (sender, e) =>
{
    if (integerTextBox1.BindableValue == null)
        MessageBox.Show("Value cleared (null)");
    else
        MessageBox.Show($"Value: {integerTextBox1.IntegerValue}");
};

用例1：带约束的财务输入 创建用于金额输入的文本框（0到999,999）：

csharp

integerTextBox1.MinValue = 0;
integerTextBox1.MaxValue = 999999;
integerTextBox1.NumberGroupSeparator = ",";
integerTextBox1.NumberGroupSizes = new int[] { 3 };

用例2：温度输入（支持正负） 允许温度范围为-50到50度：

csharp

integerTextBox1.MinValue = -50;
integerTextBox1.MaxValue = 50;
integerTextBox1.NegativeColor = Color.Blue;
integerTextBox1.PositiveColor = Color.Red;

用例3：只读显示 显示用户无法修改的值：

csharp

integerTextBox1.IntegerValue = 42;
integerTextBox1.ReadOnly = true;
integerTextBox1.ReadOnlyBackColor = Color.LightGray;

用例4：可空整数与验证 允许空值并处理错误：

csharp

integerTextBox1.BindableValueChanged += (sender, e) =>
{
    if (integerTextBox1.BindableValue == null)
        MessageBox.Show("Value cleared (null)");
    else
        MessageBox.Show($"Value: {integerTextBox1.IntegerValue}");
};

Next Steps

后续步骤

Start with Getting Started to install and create the control
Customize appearance using Visual Appearance
Handle data with Data Formatting
Respond to user interactions with Events

从入门指南开始，安装并创建控件
使用视觉外观自定义外观
使用数据格式化处理数据
使用事件响应用户交互