validate-with

コントロールまたはダイアログの検証を要求するために使用されるプロシージャです。

validator: エントリの正確性を検証するために使用される Validator です。

required?: コントロール内で値が必要であることを示します。

message: 無効なエントリが検出された場合に表示されるメッセージです。これを指定しない場合、必須フィールドが欠落していると、Validator がメッセージを提供するか、標準メッセージが使用されます。

missing-entry-message: 必要なエントリが欠落している場合に使用されるメッセージ。

dialog-on-finished?: ValidationController.dialog-on-finished? プロパティの初期値を設定します。

refocus?: 問題が見つかり、refocus? が true の場合、キーボードフォーカスがコントロールに戻され、問題を訂正できるようになります。

説明

次に示すようにコントロールで validate-with 式を使用して、ActiveTraversor (通常はコントロール) の検証を要求します。

{let md:MessageDisplay = {MessageDisplay}}
{let a:TextField = 
    {TextField
        message-display = md,
        {validate-with {NumericValidator}, required? = true}
    }
}

この例では、検証 API の最も一般的に使用される要素を示します。そこには検証されるコントロール、このエントリをチェックする Validator、および結果を表示する MessageDisplay があります。

検証ターゲットには、検証の結果を表示するために使用される message-display プロパティがあります。message-display は非ローカルオプションで、同じディスプレイを複数のコントロールで共有できます。既定の message-display は MessageDialog で、これはポップアップダイアログにメッセージを表示します。

コンテナに関する非ローカルオプションはコンテナ内部のオブジェクトに継承されるため、Dialog など、コンテナに関して message-display を設定できます。これにより、ダイアログ内のすべてのコントロールは、同じディスプレイを使用します。

MessageDisplay オブジェクトには、指定されたコントロールの色をエントリの有効性、またはエントリが必要であるか否かに基づいて変更できるプロパティがあります。

Validator のサブクラスは、数値、日付など、一般的なデータ型を検証するために提供されています。

コントロールに関して validate-with を使用した場合、検証サイクルが ValueChanged および ValueFinished イベントによって起動されます。

コントロールまたはダイアログで validate-with を使用すると、これが AttachEvent を受け取ったときにも検証サイクルが開始されます。これは、必要なエントリが欠落している場合に、最初にボタンを使用できない状態にするためです。

検証サイクルは、validate-dialog を呼び出して明示的に要求できます。検証で問題がない場合、このプロシージャは true を返します。これは、以下に示すような CommandButton の Action ハンドラでよく使用されます。

{on Action at cb:CommandButton do
    {if {validate-dialog {non-null cb.dialog}} then
        {popup-message "go!"}
    }
}

Validate および ValidationComplete のハンドラは Dialog に配置されることがよくありますが、これは、次の例に示すように複数のコントロールのエントリに関する検証を実行するためです。

現在のコントロールで検証が成功すると、次に同じ Dialog 内の他のすべてのコントロールが検証され、最後に Dialog そのものが検証されます。ダイアログが他のダイアログを含む場合、ネストされたダイアログは自動的には検証されません。ネストされたダイアログの妥当性が、それらを含むダイアログの妥当性に影響を与える場合、 validate-with 式をネストされたダイアログに加える必要があります。

RecordForm と HttpForm は Dialog のサブクラスであるため、検証に関与することに注意してください。データバインドを使用している場合は、次に示すように、ValueFinished ハンドラではなく ValidationComplete ハンドラで DataBindingTarget.update-data-binding を呼び出してください。

{TextField
    name = name,
    {bind value to name},
    {validate-with {StringValidator}, required? = true},
    {on vc:ValidationComplete at tf:TextField do
        {if vc.current? and not vc.partial? and tf.valid? then
            {tf.update-data-binding "value"}
        }
    }
}

内部的には、validate-with 式によって ValidationController が作成され、これが特定のイベント (ValueChanged、ValueFinished、および AttachEvent) を処理し、さらに 2 つのイベント Validate および ValidationComplete を発生させて検証処理を実行します。

ValidationController は、これが発生させる検証イベントも処理します。これは Validator にデリゲートし、Validator.validate を使用して Validate イベントを処理します。また、Validator.handle-validation-complete を使用して ValidationComplete イベントを処理します。検証プロセスをさらに詳しく制御する必要がある場合は、検証イベントに固有のハンドラを追加できます。

エントリの有効性を検証するためにカスタムコードが必要な場合は、コントロールまたはダイアログに関して Validate イベントのハンドラを使用します。特殊な方法によってエラーメッセージの表示を処理したい場合は、ValidationComplete イベントのハンドラを使用します。

Validate イベントには partial? フラグがあり、ユーザーエントリが不完全である (たとえば、ValueFinished ではなく、ValueChanged によって起動された) ことを示します。エントリが正しくなく、不完全である場合、エラーメッセージは表示されませんが、コントロールには無効のフラグが付けられます (「ActiveTraversor.validation-result」を参照)。

ValidationComplete は、メッセージが表示されることを示します。効率的にメッセージは 1 回しか表示されません。MessageDisplay で扱われますが、必要に応じて明示的にこのイベントを処理できます。

ValidationComplete のハンドラは、ボタンを有効にするかどうかを決定するために CommandButton に配置できます。EnablingValidator オブジェクトもあります。このオブジェクトによって、ボタンを使用可能な状態にするために有効とする必要があるコントロールまたはその名前をリストできます。ValidationComplete イベントを処理してこれを行います。

プログラミング注意事項

オブジェクトで validate-with 式を１回以上使用することは奨励されていません。不測の結果が生じることになります。

この例は、validate-with の使用法を示しています。それぞれの TextField で NumericValidator を使用して、各フィールドに数値が入力されるようにします。Dialog でカスタム検証コードを使用して、1 つの数値が他の数値より小さいかを確認します。[Go] ボタンは、全てのフィールド検証が成功するまで無効になります。

例

{let md:MessageDisplay = {MessageDisplay}}

{let low-field:TextField = 
    {TextField
        {validate-with
            {NumericValidator}, required? = true
        }
    }
}

{let high-field:TextField = 
    {TextField
        {validate-with
            {NumericValidator}, required? = true,
            message = "High is required and must be a number."
        }
    }
}

{let go-button:CommandButton = 
    {CommandButton
        label = "&Go",
        {on Action do
            {popup-message "Go!"}
        }
    }
}

{Dialog
    message-display = md,
    margin = 6pt,
    {VBox
        spacing = 6pt, width = 2.5in,
        {bold Low must be <= high},
        {Table columns = 2,
            "Low:", low-field,
            "High:", high-field
        },
        md,
        go-button
    },
    {validate-with {DialogValidator}},
    {on ve:Validate at d:Dialog do
        let domain:Domain = {StandardIntDomain}
        {try
            let h:int = {domain.parse high-field.value}
            let l:int = {domain.parse low-field.value}
            {if l > h then
                {d.mark-invalid
                    message = 
                        {text Low should be less than or equal to High}
                }
            }
         catch ex:ValidationException do
            || Do nothing, NumericValidator will report errors
        }
    },
    {on vc:ValidationComplete at d:Dialog do
        set go-button.enabled? = d.valid?
        {md.show vc, d}
    }
}