syncfusion-winforms-integer-textbox

Syncfusion Windows Forms 整数テキストボックスの実装

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• 整数値のみを受け付ける数値入力フィールドを作成する
• 値の制約（最小値と最大値の範囲）を設定する
• カスタム区切り文字を使用して数値を書式設定し、表示する
• 負の値と検証を処理する
• Windows Forms アプリケーションで値の変更や検証エラーに対応する
• 数値入力の見た目（色、境界線）を設定する

コンポーネントの概要

IntegerTextBox は、標準の TextBox から派生した、Windows Forms 用の特殊なコントロールです。

• 整数型のデータのみを受け付けて表示します
• 最小値と最大値の制約を自動的に適用します
• グループ区切りを使用したカスタムの数値書式設定をサポートします
• 値の変更や検証エラーに関するイベントを提供します
• 色やスタイルを使って見た目をカスタマイズできます
• null 値と読み取り専用状態を処理します
• 先頭のゼロと負の値の処理をサポートします

主な特徴：

• 入力を整数値のみに制限します
• 入力をリアルタイムで検証します
• null 値を処理するラッパープロパティを提供します
• テーマやローカライズに依存しない書式設定オプションを提供します
• 軽量で、ユーザーの操作にすばやく応答します

---

ドキュメントとナビゲーションガイド

現在のタスクに合ったリファレンスを選択してください。

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージの設定
• デザイナーからコントロールを追加する
• C# コードでコントロールを手動で追加する
• 最小値と最大値の制約を設定する
• 初期設定のパターン

外観

📄 参照： references/appearance.md

• 背景色の設定
• 値の種類（正の値／負の値／ゼロ）に応じたテキスト色の設定
• 境界線のスタイル設定
• 読み取り専用状態の外観
• 色のリセット方法

データ処理と書式設定

📄 参照： references/data-formatting.md

• 数値の書式設定オプション
• グループ区切り文字とグループサイズ
• 負の値とキー入力の処理
• 先頭のゼロのサポート
• null 値の管理
• 個別の色を設定した読み取り専用状態

イベントと操作

📄 参照： references/events.md

• BindableValueChanged イベントの使用方法
• IntegerValueChanged イベントの処理
• ValidationError イベントのパターン
• FormattedTextChanged と ClipTextChanged
• イベントハンドラーの実装例

---

クイックスタートの例

最小限の動作する例を示します。

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;

---

よく使われるパターン

パターン 1：値に応じた色分け

正の値を緑、負の値を赤、ゼロをグレーで表示します。

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

パターン 2：区切り文字を使った数値の書式設定

大きな数値をカスタム区切り文字で書式設定します（例：「1,234,567」）。

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

パターン 3：値の変更の処理

ユーザーが新しい値を入力したときに応答します。

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

パターン 4：エラー処理を伴う検証

検証エラーを捕捉して対応します。

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

---

主なプロパティ

プロパティ	目的	例
MaxValue	整数値の上限	integerTextBox1.MaxValue = 100;
MinValue	整数値の下限	integerTextBox1.MinValue = 0;
IntegerValue	現在の整数値を取得または設定します	int val = integerTextBox1.IntegerValue;
BindableValue	null 安全な値アクセスのためのラッパー	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;

---

一般的な使用例

使用例 1：制約付きの金額入力 金額（0～999,999）を入力するテキストボックスを作成します：

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

使用例 2：温度入力（負数と正数） -50～50 度の温度を入力できるようにします：

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

使用例 3：読み取り専用の表示 ユーザーが変更できない値を表示します：

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

使用例 4：検証付きの null 許容整数 エラー処理を行いながら null 値を許可します：

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

---

次のステップ

• はじめにから始めて、コントロールをインストールして作成します
• 外観を使って外観をカスタマイズします
• データの書式設定でデータを処理します
• イベントでユーザー操作に応答します