syncfusion-winforms-numericupdown

Syncfusion WinForms で NumericUpDownExt を実装する

このスキルでは、Syncfusion WinForms NumericUpDownExt コントロールの実装方法を説明します。XP テーマ、値の制約、16 進数表示、小数の書式設定、プロフェッショナルな外観機能を備えた、拡張版の数値アップダウンコントロールです。

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

次のようなニーズがある場合に、このスキルを使用してください。

• XP テーマに対応した拡張数値アップダウンコントロールを実装する
• 値の制約（Minimum、Maximum、Increment の値）を設定する
• 数値入力で16 進数の値を表示する
• 小数点以下の桁数や桁区切りを設定して数値を書式設定する
• テーマ付きの境界線（FixedSingle、Fixed3D、ThemedBorder）を適用する
• 負の値に別の色（NegativeForeColor）を使用する
• 値の変更にキーボードの矢印キー入力を有効にする
• キーボードによる大きな値の入力に対応する
• テキストとボタンの配置（左／右／中央）を設定する
• 一貫したテーマを適用したプロフェッショナルな数値入力フォームを作成する
• 標準のNumericUpDownを、見た目を強化した代替コントロールに置き換える

数値入力コントロールで、外観のテーマ設定や高度な書式設定が重要な場合に、NumericUpDownExt が最適です。

コンポーネントの概要

NumericUpDownExt は、XP テーマと拡張機能を備えた、標準の WinForms NumericUpDown を拡張する高度な数値アップダウンコントロールです。次の機能を提供します。

• XP テーマのサポート：標準の .NET コントロールにはない、洗練された外観と操作感
• 値の制約：Minimum、Maximum、Increment プロパティ
• 表示オプション：小数点以下の桁数、桁区切り、16 進数形式
• 外観のカスタマイズ：色、境界線、配置のオプション
• テーマ付きの境界線：FixedSingle、Fixed3D、None、ThemedBorder
• キーボードのサポート：矢印キー、大きな値の入力
• 負の値のスタイル設定：負の数に使用する個別の前景色
• レイアウトの制御：MinSize、MaxSize プロパティ

標準の NumericUpDown との主な違い： NumericUpDownExt は、XP テーマ、16 進数表示、テーマ付きの境界線、負の値の色の設定を追加します。

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

はじめにと基本設定

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

次のようなニーズがある場合は、このリファレンスを参照してください。

• アセンブリの依存関係と NuGet パッケージのインストール
• デザイナーまたはコードによる NumericUpDownExt の作成
• 基本的なプロパティと設定
• フォームへの NumericUpDownExt の追加
• コントロールの階層の理解
• 最小限の完全な動作例

値の設定と制約

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

次のようなニーズがある場合は、このリファレンスを参照してください。

• 現在の数値を設定する Value プロパティ
• Minimum と Maximum の制約
• ステップ値を設定する Increment プロパティ
• 16 進数表示モード
• 16 進数表現用の HexValue プロパティ
• UpButton／DownButton メソッド
• 値の制約の例とパターン

表示設定

📄 参照先： references/display-settings.md

次のようなニーズがある場合は、このリファレンスを参照してください。

• 小数部分を表示する DecimalPlaces プロパティ
• 大きな数値に使用する ThousandsSeparator
• 表示書式の設定オプション
• 通貨とパーセンテージの書式設定
• さまざまな数値形式の例

外観のカスタマイズ

📄 参照先： references/appearance-customization.md

次のようなニーズがある場合は、このリファレンスを参照してください。

• 背景色と前景色
• 負の値に使用する NegativeForeColor
• 境界線のスタイル（FixedSingle、Fixed3D、None）
• ThemedBorder プロパティ
• テキストとボタンの配置
• レイアウト設定（MaxSize、MinSize）
• カスタムスタイル設定の完全な例

動作設定

📄 参照先： references/behavior-settings.md

次のようなニーズがある場合は、このリファレンスを参照してください。

• キーボード入力に使用する InterceptArrowKeys プロパティ
• 読み取り専用モードの設定
• 大きな値の入力に対応するキー
• 動作の設定オプション
• ユーザー操作のパターン

テーマとビジュアルスタイル

📄 参照： references/themes-and-styles.md

次の情報が必要な場合は、このリファレンスを参照してください。

• ビジュアルスタイルの概要
• NumericUpDownExt へのテーマの適用
• XP テーマの外観と操作感
• アプリケーションとのテーマ統合
• スタイルに関するベストプラクティス

クイックスタートの例

制約を設定した NumericUpDownExt コントロールを作成する最小限の例を示します。

using Syncfusion.Windows.Forms.Tools;
using System;
using System.Drawing;
using System.Windows.Forms;

public class NumericUpDownExample : Form
{
    private NumericUpDownExt numericUpDownExt1;
    
    public NumericUpDownExample()
    {
        // Create NumericUpDownExt
        numericUpDownExt1 = new NumericUpDownExt();
        numericUpDownExt1.Location = new Point(70, 29);
        numericUpDownExt1.Size = new Size(120, 20);
        
        // Set value constraints
        numericUpDownExt1.Minimum = 0;
        numericUpDownExt1.Maximum = 100;
        numericUpDownExt1.Value = 50;
        numericUpDownExt1.Increment = 5;
        
        // Set display formatting
        numericUpDownExt1.DecimalPlaces = 2;
        numericUpDownExt1.ThousandsSeparator = true;
        
        // Add to form
        this.Controls.Add(numericUpDownExt1);
        
        this.Text = "NumericUpDownExt Example";
        this.Size = new Size(300, 150);
    }
}

結果： 値の範囲が 0～100 で、5 ずつ増加し、桁区切り記号付きで小数点以下 2 桁を表示する数値アップダウンコントロールです。

よくあるパターン

通貨入力コントロール

パターン： 適切な書式設定で通貨入力用の数値コントロールを作成します。

// Currency input with constraints
NumericUpDownExt currencyInput = new NumericUpDownExt();
currencyInput.Location = new Point(100, 20);
currencyInput.Size = new Size(120, 20);

// Value settings
currencyInput.Minimum = 0;
currencyInput.Maximum = 999999.99m;
currencyInput.Increment = 0.01m;
currencyInput.Value = 0;

// Display formatting
currencyInput.DecimalPlaces = 2;
currencyInput.ThousandsSeparator = true;

// Add label for context
Label label = new Label();
label.Text = "Price: $";
label.Location = new Point(50, 23);
label.AutoSize = true;

this.Controls.Add(label);
this.Controls.Add(currencyInput);

使用場面： セント単位の精度と大きな数値の書式設定に対応した通貨入力が必要な場合です。

パーセンテージセレクター

パターン： パーセンテージ値（0～100）用の数値コントロールです。

NumericUpDownExt percentInput = new NumericUpDownExt();
percentInput.Location = new Point(100, 50);
percentInput.Size = new Size(100, 20);

// Percentage constraints
percentInput.Minimum = 0;
percentInput.Maximum = 100;
percentInput.Increment = 5;
percentInput.Value = 50;
percentInput.DecimalPlaces = 1;

// Add % suffix label
Label percentLabel = new Label();
percentLabel.Text = "%";
percentLabel.Location = new Point(205, 53);
percentLabel.AutoSize = true;

this.Controls.Add(percentInput);
this.Controls.Add(percentLabel);

使用場面： 範囲が制限されたパーセンテージ入力が必要な場合です。

16 進数カラー値の入力

パターン： 16 進数形式で値を表示、編集します。

NumericUpDownExt hexInput = new NumericUpDownExt();
hexInput.Location = new Point(100, 80);
hexInput.Size = new Size(120, 20);

// Hex mode for color values
hexInput.Hexadecimal = true;
hexInput.Minimum = 0;
hexInput.Maximum = 0xFFFFFF; // Max RGB value
hexInput.Increment = 0x10;
hexInput.Value = 0xFF5733; // Example color

// Add label
Label hexLabel = new Label();
hexLabel.Text = "Color (Hex):";
hexLabel.Location = new Point(20, 83);
hexLabel.AutoSize = true;

this.Controls.Add(hexLabel);
this.Controls.Add(hexInput);

使用場面： 色、メモリアドレス、またはバイト値の 16 進数入力が必要な場合です。

主なプロパティ

値のプロパティ

プロパティ	型	説明	使用場面
Value	decimal	現在の数値	コントロールの値を取得／設定
Minimum	decimal	許可される最小値	下限を設定
Maximum	decimal	許可される最大値	上限を設定
Increment	decimal	値の変更幅	増分を設定
Hexadecimal	bool	16 進数形式で表示	16 進数値の入力
HexValue	string	16 進数表現（読み取り専用）	16 進数の文字列を取得

表示プロパティ

プロパティ	型	説明	使用場面
DecimalPlaces	int	小数点以下の桁数	小数の精度
ThousandsSeparator	bool	桁区切り記号を表示	大きな数値の書式設定

外観プロパティ

プロパティ	型	説明	使用場面
BackColor	Color	背景色	背景をカスタマイズ
ForeColor	Color	テキストの色	テキストの色をカスタマイズ
NegativeForeColor	Color	負の値の色	負の数を強調表示
BorderStyle	BorderStyle	境界線のスタイル（FixedSingle/Fixed3D/None）	コントロールの外観
ThemedBorder	bool	テーマ付きの境界線を使用	モダンな外観

動作プロパティ

プロパティ	型	説明	使用場面
InterceptArrowKeys	bool	矢印キー入力を許可	キーボードで値を変更
ReadOnly	bool	値の編集を禁止	表示専用モード
UpDownAlign	LeftRightAlignment	ボタンの位置（Left/Right）	レイアウトをカスタマイズ
TextAlign	HorizontalAlignment	テキストの配置	左／右／中央揃え

よくある使用例

設定フォーム

アプリケーション設定用の数値入力：

• フォントサイズセレクター（8～72 pt）
• タイムアウト値（秒／分）
• バッファーサイズの設定
• スレッド数の設定

金融アプリケーション

通貨とパーセンテージの入力：

• 小数精度を指定した価格入力
• 割引率セレクター
• 税率の入力
• 口座残高の表示

科学／工学ツール

高精度の数値入力：

• 小数点以下の桁数を指定した測定値
• キャリブレーションパラメーター
• 制約付きの計算入力
• 単位変換インターフェース

カラーピッカー

16 進数カラー値の入力：

• RGB コンポーネント値（0～255）
• 16 進数カラーコード（#000000～#FFFFFF）
• アルファチャンネル値
• カラーパレットエディター

実装チェックリスト

NumericUpDownExt を実装する際は、次の点を確認してください。

• ✅ 必要なアセンブリを参照する（Syncfusion.Tools.Windows.dll など）
• ✅ 名前空間を含める（Syncfusion.Windows.Forms.Tools）
• ✅ NumericUpDownExt インスタンスを作成して設定する
• ✅ 値の制約を設定する（Minimum、Maximum、Increment）
• ✅ 表示形式を設定する（DecimalPlaces、ThousandsSeparator）
• ✅ レイアウト用に位置とサイズを指定する
• ✅ Value プロパティで既定値を設定する
• ✅ 必要に応じて ValueChanged のイベントハンドラーを追加する
• ✅ ビジネスルールに対する検証を実装する
• ✅ 境界値（最小値、最大値、0、負の値）でテストする

トラブルシューティングのクイックリファレンス

問題： 矢印キーを押しても値が変わらない

• InterceptArrowKeys = true を設定する
• コントロールにフォーカスがあることを確認する
• ReadOnly が false であることを確認する

問題： 小数点以下の桁数が表示されない

• DecimalPlaces プロパティに必要な桁数を設定する
• Value に小数部分があることを確認する
• Value が整数のみになっていないか確認する

問題： 桁区切り記号が表示されない

• ThousandsSeparator = true を設定する
• 値が 1000 以上であることを確認する
• カルチャ設定が桁区切り記号に対応していることを確認する

問題： 範囲外の値を設定できない

• Minimum および Maximum プロパティを確認する
• 設定する値が制約範囲内にあることを確認する
• 大きな値には decimal 型を使用する

問題： 16 進数表示が機能しない

• Hexadecimal = true を設定する
• 値が有効な 16 進数の範囲内であることを確認する
• 16 進数文字列の読み取りには HexValue プロパティを使用する

問題： 負の値が別の色で表示されない

• NegativeForeColor プロパティを明示的に設定する
• Minimum が負の値を許可していることを確認する
• 値が実際に負であることを確認する

まとめ

NumericUpDownExt は、次の機能を備えた拡張数値入力機能を提供します。

• XP テーマ：モダンな外観
• 値の制約：最小値／最大値／増分の制御
• 表示形式：小数点以下の桁数、桁区切り記号、16 進数
• 視覚的なカスタマイズ：色、境界線、配置、テーマ適用の外観

WinForms アプリケーションでプロフェッショナルな数値入力コントロールを作成する際に、テーマ設定、高度な書式設定、値の精密な制御が重要な場合は、NumericUpDownExt を使用してください。