【実務・中級編】Windows Formsにおけるカンマ編集・数値フォーマットの悩みを解決：MaskedTextBoxとNumericUpDownの長所を融合したカスタム数値入力コントロール – Visual Basic (VB / VB.NET)解析バイブル

標準コントロールの限界を超えろ：業務システムに求められる「真の数値入力コントロール」を設計する

業務アプリケーションの開発現場において、多くのエンジニアが「標準コントロールの組み合わせ」という罠に陥っている。

金額入力に `NumericUpDown` を使えば、型安全性は確保できる。しかし、「未入力（Null）」と「ゼロ」を明確に区別したいというビジネス要件に直面した瞬間、その設計は崩壊する。一方で、`MaskedTextBox` を使えばフォーマットは制御できるが、数値としてのパース（解析）や、カーソル位置の制御、デリケートな入力操作において、ユーザーにストレスを与える「使いにくいUI」へと変貌する。

プロフェッショナルな現場で求められるのは、「入力時は自由度が高く、フォーカスが外れた瞬間に完璧な書式に整い、かつデータ層（DB）との整合性を保つ」コントロールである。

本稿では、Windows Formsにおける標準コントロールの欠点を補完し、堅牢性と操作性を極限まで高めたカスタムコントロールの設計思想とその実装を伝授する。

1. なぜ標準コントロールでは「不十分」なのか

設計の前に、我々が戦っている敵を正しく定義しよう。

NumericUpDown の限界

• 「空文字」が許されない: 常に何らかの数値（デフォルトは0）を保持しようとするため、DBの `NULL` を表現する際に、アプリケーション層で「0なのかNULLなのか」という不毛な判定ロジックを量産することになる。
• 表示の硬直性: 桁区切りカンマの制御や、特定の書式への動的な切り替えが極めて困難である。

MaskedTextBox の限界

• カーソル制御の難解さ: マスクに基づいた入力制限は強力だが、ユーザーが数字を書き換えようとした際のカーソル移動が不自然になりやすく、入力体験（UX）を著しく損なう。
• 数値としての扱い: 本質的に「文字列」を扱うためのコントロールであるため、常に `Decimal.TryParse` 等による変換コストとエラーハンドリングが付きまとう。

TextBox + 手動実装 の罠

• イベントの再入（Re-entrancy）: `TextChanged` イベント内で文字列を整形しようとすると、再び `TextChanged` が走り、無限ループやカーソル位置の異常なジャンプを引き起こす。これは初心者が必ず踏む地雷である。

2. アーキテクチャ設計：状態遷移の分離

我々が構築すべきは、「入力モード（Editing State）」と「表示モード（Display State）」を明確に分離したコントロールである。

1. 入力モード (On Enter): フォーカスを得た際、カンマを除去し、全選択状態にする。ユーザーは純粋な数値のみを意識して入力できる。
2. 表示モード (On Leave): フォーカスを失った際、3桁区切りカンマを適用し、整形された文字列を表示する。
3. データ整合性: プロパティとして `Value` (Decimal型) を持ち、UIの文字列ではなく「値そのもの」でデータ層と通信する。

3. 実装：SmartNumericTextBox

以下に、プロダクション環境でそのまま利用可能な、堅牢な実装例を示す。このコードは、カーソル位置の制御と、再入防止（イベントの連鎖防止）を考慮して設計されている。

Imports System.ComponentModel

''' <summary>
''' 金額や数量の入力に特化した、高機能数値入力コントロール。
''' 3桁区切り、未入力(Null)対応、フォーカス時の全選択機能を備える。
''' </summary>
<DesignerSerializationVisibility(DesignerSerializationVisibility.Content)>
Public Class SmartNumericTextBox
    Inherits TextBox

    ' --- プライベート変数 ---
    Private _value As Decimal?
    Private _isFormatting As Boolean = False ' 再入防止フラグ

    ' --- プロパティ ---

    ''' <summary>
    ''' 入力された数値の値を返します。未入力の場合は Nothing を返します。
    ''' </summary>
    <Bindable(True)>
    <Category("Appearance")>
    <Description("コントロールの数値値をDecimal型で取得・設定します。")>
    Public Property Value As Decimal?
        Get
            Return _value
        End Get
        Set(value As Decimal?)
            _value = value
            ' 値が変更されたとき、表示を更新するが、フォーカスがある間はユーザーの入力を妨げない
            If Not Me.Focused Then
                UpdateDisplay()
            End If
        End Set
    End Property

    ''' <summary>
    ''' 小数点以下の桁数を指定します。
    ''' </summary>
    <Category("Appearance")>
    Public Property DecimalPlaces As Integer = 0

    ' --- コンストラクタ ---
    Public Sub New()
        ' 初期設定
        Me.SelectAllOnEnter = True
    End Sub

    ' --- イベントオーバーライド ---

    ''' <summary>
    ''' フォーカスを得た時の動作
    ''' </summary>
    Protected Overrides Sub OnEnter(e As EventArgs)
        MyBase.OnEnter(e)
        ' 入力しやすくするため、カンマを除去して生の数字を表示
        FormatForEditing()
        ' 全選択してユーザーの入力を促す
        Me.SelectAll()
    End Sub

    ''' <summary>
    ''' フォーカスを失った時の動作
    ''' </summary>
    Protected Overrides Sub OnLeave(e As EventArgs)
        MyBase.OnLeave(e)
        ' 表示用に整形
        UpdateDisplay()
    End Sub

    ''' <summary>
    ''' キー入力の制御
    ''' </summary>
    Protected Overrides Sub OnKeyPress(e As KeyPressEventArgs)
        MyBase.OnKeyPress(e)

        ' 数字、バックスペース、および小数点(設定されている場合)のみ許可
        Dim isDigit As Boolean = Char.IsDigit(e.KeyChar)
        Dim isControl As Boolean = Char.IsControl(e.KeyChar)
        Dim isDecimalSeparator As Boolean = (e.KeyChar = "." AndAlso DecimalPlaces > 0 AndAlso Not Me.Text.Contains("."))

        If Not (isDigit OrElse isControl OrElse isDecimalSeparator) Then
            e.Handled = True ' 無効な入力を破棄
        End If
    End Sub

    ' --- ヘルパーメソッド ---

    ''' <summary>
    ''' 入力しやすい形式（カンマなし）に変換
    ''' </summary>
    Private Sub FormatForEditing()
        If _value.HasValue Then
            ' カンマを除去した生の数値文字列にする
            Me.Text = _value.Value.ToString("F" & DecimalPlaces)
        Else
            Me.Text = String.Empty
        End If
    End Sub

    ''' <summary>
    ''' 表示用の形式（3桁区切り）に変換
    ''' </summary>
    Private Sub UpdateDisplay()
        _isFormatting = True ' 再入防止
        Try
            Dim parsedValue As Decimal
            ' 現在のテキストから数値を解析
            If Decimal.TryParse(Me.Text.Replace(",", ""), parsedValue) Then
                _value = parsedValue
                ' 3桁区切り形式で表示
                Dim format As String = "N" & DecimalPlaces
                Me.Text = _value.Value.ToString(format)
            Else
                ' 解析失敗（空文字など）の場合はNullとして扱う
                _value = Nothing
                Me.Text = String.Empty
            End If
        Finally
            _isFormatting = False
        End Try
    End Sub

    ''' <summary>
    ''' テキストが変更された際の処理
    ''' </summary>
    Protected Overrides Sub OnTextChanged(e As EventArgs)
        ' フォーマット処理中やフォーカスがある間は、自動変換を行わない（カーソルジャンプ防止）
        If _isFormatting OrElse Me.Focused Then
            MyBase.OnTextChanged(e)
            Return
        End If

        ' フォーカスが外れている状態でテキストが直接書き換わった場合（コードからの操作等）
        UpdateDisplay()
        MyBase.OnTextChanged(e)
    End Sub

End Class

4. 実務における運用上の注意点

このコントロールを導入する際、単に配置するだけでは不十分だ。アーキテクトとして、以下の2点についてチームに徹底させなければならない。

① データベース連携（DBNullの扱い）

このコントロールの最大の利点は `Decimal?` (Nullable Decimal) を保持している点だ。
データ層への保存時には、以下のようなパターンを用いること。

' 悪い例: 0で埋めてしまう（NULLと0の区別が消える）
cmd.Parameters.AddWithValue("@Amount", myTextBox.Value.GetValueOrDefault(0))

' 良い例: 型を意識してDBNullを渡す
cmd.Parameters.Add("@Amount", SqlDbType.Decimal).Value = 
    If(myTextBox.Value.HasValue, DirectCast(myTextBox.Value.Value, Object), DBNull.Value)

② データのバリデーション

`SmartNumericTextBox` は「数値としての妥当性」は保証するが、「業務ルールとしての妥当性」（例：単価がマイナスであってはならない、予算を超えてはならない）は保証しない。
UIコントロールの責務と、ビジネスロジック層の責務を混同してはならない。バリデーションは必ず、コントロールの `Leave` イベントではなく、保存処理の直前、あるいはViewModel/Logic層で行うべきだ。

5. 結論

優れた業務アプリケーションは、ユーザーの「思考」を妨げない。
入力中にカンマが勝手に現れてカーソルが飛ぶ、あるいは「未入力」を表現できずに「0」を入力させられるといった些細なストレスの積み重ねが、システムの信頼性を削り取っていく。

今回提示した `SmartNumericTextBox` のような、状態管理を徹底したカスタムコントロールを資産として蓄積すること。それが、単なる「ツールを作る人」から「システムを設計するエンジニア」へと昇華するための第一歩である。