syncfusion-winforms-percent-textbox

Syncfusion WinForms PercentTextBox の実装

PercentTextBox は、Windows Forms アプリケーションでパーセンテージ値を表示、入力、管理できる、テキストボックス派生コントロールです。パーセンテージ入力向けに、書式設定、検証、データバインディングの機能が組み込まれています。

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

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

• Windows Forms アプリケーションでユーザーからパーセンテージ値を収集する
• パーセンテージデータを一貫した書式で表示する
• 最小値／最大値の範囲内でパーセンテージ入力を検証する
• パーセンテージ値をデータソースにバインドする
• 値の変更や検証エラーをプログラムで処理する
• パーセンテージの数値書式（小数桁数、区切り記号）をカスタマイズする
• 同じ値をパーセンテージ表現と小数表現の両方で扱う

コンポーネントの概要

PercentTextBox は Windows Forms の TextBox を継承し、次の機能を追加します。

• パーセンテージの自動書式設定と検証
• 複数の値表現（PercentValue、DoubleValue、BindableValue）への対応
• 検証時の最小値／最大値の制約適用
• 数値書式（小数桁数、区切り記号）のカスタマイズ
• 値の変更と検証に対応する豊富なイベントシステム
• null 値の処理
• 負の値に対するキーボード入力制御

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

目的に応じてリファレンスを選択してください。

はじめに

📄 参照先： references/getting-started.md

• インストールとアセンブリ参照
• デザイナーとコードによるコントロールの追加
• 基本的な値の初期化
• 最小限の実行可能な例

値の管理

📄 参照先： references/value-management.md

• PercentValue プロパティと DoubleValue プロパティの違い
• データバインディング用の BindableValue と BindablePercentValue
• DefaultValue プロパティの使用方法
• 値の取得と変換のパターン

制約と検証

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

• パーセンテージ値の最小値と最大値の設定
• 検証時の最小値／最大値の適用
• null 値の処理（AllowNull、NullString、NullFormat）
• ValidationError イベントの処理
• 検証エラーを防止する方法

書式設定と表示

📄 参照先： references/formatting-and-display.md

• 小数桁数（PercentDecimalDigits）のカスタマイズ
• 小数点区切り記号と桁区切り記号
• グループサイズの設定
• 書式設定のカスタマイズ例
• 数値書式パターン

動作と入力

📄 参照先： references/behavior-and-input.md

• 負の値の入力処理（NegativeInputPendingOnSelectAll）
• 書式設定前のテキストを取得する ClipText プロパティ
• ユーザー入力の処理
• キーボード動作の制御

イベントとデータバインディング

📄 参照先： references/events-and-data-binding.md

• BindablePercentValueChanged イベント
• BindableValueChanged イベント
• DoubleValueChanged イベント
• BindablePercentValue へのデータバインディング
• イベントハンドラーの実装パターン
• 値の変更への応答

プロパティと API リファレンス

📄 参照先： references/properties-and-api-reference.md

• カテゴリ別に整理されたプロパティの全リファレンス
• 主要なメソッド（ResetMaxValue、ResetMinValue など）
• 読み取り専用プロパティ（FormattedText、ClipText）
• 一般的なシナリオ向けのクイック検索ガイド

クイックスタートの例

基本設定（デザイナー）

1. ツールボックスからフォームに PercentTextBox をドラッグします
2. PercentValue プロパティに初期値（例：50）を設定します
3. 制約のために MaxValue と MinValue を設定します
4. 変更を処理するために BindablePercentValueChanged イベントを購読します

基本設定（コード）

using Syncfusion.Windows.Forms.Tools;

// Create instance
PercentTextBox percentTextBox1 = new PercentTextBox();
this.Controls.Add(percentTextBox1);

// Set value
percentTextBox1.PercentValue = 50;

// Set constraints
percentTextBox1.MaxValue = 100;
percentTextBox1.MinValue = 0;

// Subscribe to value changed event
percentTextBox1.BindablePercentValueChanged += (sender, e) => 
{
    Console.WriteLine($"Percent: {percentTextBox1.PercentValue}%");
};

一般的なパターン

パターン 1：既定値と制約を設定して初期化する

var percentBox = new PercentTextBox();
percentBox.PercentValue = 25;
percentBox.MinValue = 0;
percentBox.MaxValue = 100;
percentBox.PercentDecimalDigits = 2;

パターン 2：データソースにバインドする

percentTextBox1.DataBindings.Add("BindablePercentValue", dataSource, "PercentageField");

パターン 3：検証エラーを処理する

percentTextBox1.ValidationError += (sender, e) =>
{
    MessageBox.Show($"Invalid input: {e.ErrorMessage}");
};

パターン 4：数値書式をカスタマイズする

percentTextBox1.PercentDecimalDigits = 3;
percentTextBox1.PercentDecimalSeparator = ".";
percentTextBox1.PercentGroupSeparator = ",";
percentTextBox1.PercentGroupSizes = new int[] { 2 };

主なプロパティ

プロパティ	型	用途
PercentValue	double	パーセント値（0～100）を取得／設定します
DoubleValue	double	小数値（0～1）を取得／設定します
BindablePercentValue	double?	データバインディング用の null 許容パーセント値です
BindableValue	double?	データバインディング用の null 許容小数値です
MaxValue	double	許容される最大値です
MinValue	double	許容される最小値です
DefaultValue	double	リセット時の既定値です
AllowNull	bool	null／空の入力を許可します
NullString	string	null の場合に表示するテキストです
PercentDecimalDigits	int	小数点以下の桁数です
PercentDecimalSeparator	string	小数点の区切り文字です
PercentGroupSeparator	string	桁区切り文字です
PercentGroupSizes	int[]	桁区切りのグループサイズです
NegativeInputPendingOnSelectAll	bool	すべて選択したときに負の値を許可します

一般的なユースケース

ユースケース 1：合計に対する割合

全体に対する割合を表す、0～100 の範囲内である必要がある値を入力します。

• 参照： value-management.md + constraints-and-validation.md

ユースケース 2：割引率またはコミッション率

特定の小数精度で計算するためのパーセント率を受け付けます。

• 参照： formatting-and-display.md + value-management.md

ユースケース 3：入力検証付きのフォーム

無効なパーセント値の入力を防ぎ、エラーを表示するフォームを作成します。

• 参照： constraints-and-validation.md + events-and-data-binding.md

ユースケース 4：データバインディングのシナリオ

PercentTextBox をデータモデルのフィールドにバインドし、自動的に同期します。

• 参照： events-and-data-binding.md + value-management.md

---

次へ： 現在のニーズに応じて上記のリファレンスファイルを選択してください。PercentTextBox を初めて使用する場合は、getting-started.md から始めてください。