syncfusion-winforms-currency-textbox

Syncfusion Windows Forms CurrencyTextBox の実装

Syncfusion CurrencyTextBox は、System.Windows.Forms.TextBox から派生した特殊なテキスト入力コントロールで、 通貨に特化した検証、書式設定、動作を提供します。キーボード入力の検証、カルチャに応じた小数点の書式設定、 値の制約を自動的に処理します。

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

• 自動検証機能を備えた通貨入力フィールドを作成する
• 財務データ入力フォーム（請求書、支払い、予算）を構築する
• 正負の値を色分けして通貨を表示する
• 小数精度と桁区切り文字を扱う
• 通貨データを使ったクリップボード操作を処理する
• 値を乗算するキーボードショートカット（Mega、Kilo など）を追加する
• 通貨値の最小値と最大値を適用する
• 大きな数値のオーバーフローインジケーターを表示する

コンポーネントの概要

CurrencyTextBox コントロールはユーザーのキーボード入力をインターセプトし、無効な通貨文字の入力を防ぎます。 小数桁数、桁区切り文字、通貨記号に基づいて表示を自動的に書式設定します。 標準の TextBox とは異なり、最小値／最大値の範囲で値を検証し、通貨に特化したイベントをサポートします。

主な機能：

• キーボード入力の自動検証
• カルチャに応じた小数点の書式設定
• 最大値／最小値の制約と適用
• 正の値、負の値、ゼロ値の色分け
• 書式の削除オプションを備えたクリップボードのサポート
• ツールチップ付きオーバーフローインジケーター
• 値を乗算するキーボードショートカット
• 無効な入力を処理する ValidationError イベント

ドキュメントの参照ガイド

はじめに

📄 参照： references/getting-started.md

• インストールとアセンブリの依存関係
• プロジェクトの作成とコントロールの追加
• デザイナーを使ったコントロールの作成とコードによる作成
• MaxValue／MinValue 制約の設定
• 通貨記号の設定
• 基本的なコントロールのプロパティ

テキストフィールドのカスタマイズ

📄 参照： references/text-field-customization.md

• テキストの表示と配置（Left、Center、Right）
• 折り返し表示を含む複数行のサポート
• パスワード文字によるマスキング
• 空の状態でのバナーテキスト
• 数値と小数桁の書式設定
• 負の値と符号の処理
• Null 文字列の設定

値の書式設定

📄 参照： references/value-formatting.md

• DecimalValue によるプログラムからのアクセス
• 通貨記号のカスタマイズ
• 数値の書式設定（小数点より前の合計桁数）
• 小数桁の精度
• 桁区切り文字の設定
• 末尾の小数点以下のゼロの削除
• 正負の通貨パターン

イベント処理

📄 参照： references/event-handling.md

• キーボードショートカット用の KeyDown イベント
• 乗数キー（G、M、K：Giga／Mega／Kilo）を追加する
• 無効な入力用の ValidationError イベント
• StartPosition を使ったエラーメッセージの処理
• 視覚的なフィードバックに ErrorProvider を使用する
• カスタム検証のシナリオ

外観のカスタマイズ

📄 参照： references/appearance-customization.md

• 境界線のスタイル（FixedSingle、Fixed3D、None）
• 3D 境界線の効果（Raised、Sunken、Flat など）
• 境界線の色と辺の設定
• 値による色分け（正、負、ゼロ）
• 読み取り専用時の背景色
• ビジュアルスタイルの適用

高度な機能

📄 参照： references/advanced-features.md

• 書式設定オプションを備えたクリップボードのサポート
• オーバーフローインジケーターの表示
• オーバーフローインジケーターのツールチップ
• 複数のクリップボードモード
• データの保持方法

検証と制約

📄 参照： references/validation-and-constraints.md

• 最小値／最大値の境界の設定
• 検証時の制約の適用
• 選択したテキストがある場合の負の値の入力動作
• AllowNull の設定
• NullString によるカスタム表示値
• 値の範囲の適用

クイックスタートの例

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

一般的なパターン

通貨入力フォーム

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

損益表示

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

プレースホルダー付きの任意入力の金額

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

大きな数値を入力するためのキーボードショートカット

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

主なプロパティのリファレンス

プロパティ	型	用途	一般的な値
DecimalValue	decimal	プログラムから数値を取得・設定します	有効な任意の decimal 値
CurrencySymbol	string	通貨記号を表示します	"$", "€", "£", "¥"
CurrencyDecimalDigits	int	表示する小数点以下の桁数	2, 3, 4
CurrencyGroupSeparator	string	桁区切り記号	",", ".", " "
MaxValue	decimal	許容される最大値	999999.99, 100000 など
MinValue	decimal	許容される最小値	0, -999999.99 など
PositiveColor	Color	正の値の色	Color.Black, Color.Green
NegativeColor	Color	負の値の色	Color.Red, Color.Maroon
ZeroColor	Color	ゼロの値の色	Color.Gray, Color.DarkGray
TextAlign	HorizontalAlignment	テキストの配置	Left, Center, Right
BorderStyle	BorderStyle	境界線の外観	FixedSingle, Fixed3D, None
AllowNull	bool	空または null の値を許可します	true, false
ShowOverflowIndicator	bool	値が範囲を超えたときにインジケーターを表示します	true, false

シナリオ別のユースケース

金融アプリケーション

• 正負の値を色分けします
• データ型のオーバーフローを防ぐために MaxValue を設定します
• 監査ログに ValidationError を処理します
• 貼り付け操作でクリップボードをサポートします

予算入力フォーム

• 適切な MaxValue（例：999999.99）を設定します
• 数値入力の慣例に従い TextAlign.Right を使用します
• 必須フィールドにバナーテキストを表示します
• 金額を正の値にする必要がある場合は、MinValue を 0 に設定します

複数通貨の表示

• ユーザーのロケールに応じて CurrencySymbol を変更します
• CurrencyDecimalDigits を統一します（通常は 2）
• 地域に応じて CurrencyGroupSeparator を調整します
• データベースでは DecimalValue を一貫した形式で表示します

大きな数値の処理

• キーボードの乗数ショートカット（G、M、K）を有効にします
• 表示領域を超える値には ShowOverflowIndicator を使用します
• RemoveDecimalZeros プロパティで小数点以下のゼロを取り除きます
• CurrencyNumberDigits で数値の桁数を増やします

次のステップ

• タスクに合ったリファレンスファイルを選択します
• コード例に従ってコントロールを実装します
• 有効な値と境界値の両方でテストします
• 無効な入力には ValidationError イベントを処理します
• ビジネスロジックには DecimalValue を、表示には Text を使用します