DataBindingContext

DataBinding のデータソース。

説明

DataBindingContext は、そこに登録されている DataBinding のデータ表示、編集、同期機能を提供します。

バインドは、このコンテキストに明示的に関連付けることも、グラフィック階層の位置によって自動的に登録することもできます。詳細は DataBinding.auto-register? を参照してください。

オーバーライド

実装では、DataBindingContext.get-data で元のデータソースからデータを読み取る方法を指定する必要があります。特にクラスの記述では、ソース内のデータアイテムをアドレスするためにこのメソッドに与えられる data-selector の型を指定して記述する必要があります。

実装でデータソースが更新されるようにするには、DataBindingContext.validate-internal と DataBindingContext.update-internal メソッドをオーバーライドする必要があります。既定ではこれらのメソッドはエラーをスローして、コンテキスト内のデータが変更不可能であることを示します。

また実装において、特定のバインドの get-data を呼び出して返されるデータが変更するときには、バインドをリフレッシュする必要があります。この状況は、たとえば元のデータが外的要因により変化したか、コンテキストの「カーソル」位置が移動したなどの原因で起こることがあります。簡単な更新方法の 1 つは、このような変更が起きたときにコンテキストで DataBindingContext.refresh (全バインドをリフレッシュする) を呼び出すことです。より選択的かつ効率的な更新は DataBinding.refresh を使って実装できます。

このオブジェクトを作成します。

登録済みのバインドにペンディング中の更新があるかどうか調べます。

オーバーライド

これは、DataBinding.pending-update? を呼び出し、登録されているすべてのバインドを繰り返し処理する便利なメソッドです。通常はオーバーライドしません。

このコンテキストに現在登録されている DataBinding。

説明

アプリケーションではこのコレクションを直接変更しないでください。

アプリケーションでは、これらのバインドの DataBinding.target がすべてnull 以外の値であると考えてください。

このコンテキストのデータをバインドプロパティに適した値に変換します (可能な場合)。

プログラミング注意事項

通常はアプリケーションから直接呼び出しません。このメソッドは DataBinding.refresh が内部で呼び出します。

value: フォーマットされる値。

binding: この変換が行われる DataBinding。このコンテキストに登録されている必要があります。

戻り値

バインドプロパティに設定する値か、ターゲットのプロパティを「設定解除」することを意味する DataBinding.unset。

説明

このメソッドが変換を実行できない場合、または実行を望まない場合には、ターゲットで使われた入力値をそのまま返すことがあります。ただしこのメソッドが value にエラーがあると判定した場合、エラーをスローすることがあります。

このメソッドの代わりに指定して使える DataBinding.format も参照してください。

オーバーライド

このメソッドの既定の実装では、以下の変換を実行します。

null 値は DataBinding.unset に変換されます。
String かそのスーパー型の 1 つにフォーマットする場合は、既定のファクトリー String.default#factory が使われます。

その他の場合、変換は適用されません。追加のフォーマット機能を持つサブクラスでは、このメソッドをオーバーライドする必要があります。

data-selector に関連付けられたデータを取得します。

data-selector: any 型。サブクラスではこの引数に適切な型を指定する必要があります。入力された値がこのコンテキストに適さない場合はエラーがスローされます。

戻り値

このメソッドは 2 つの値を返します。

データ : any 型のデータ (存在する場合)。
exists? : data-selector に現在使用可能なデータがない場合は false (たとえば、コンテキスト上のカーソルが最後のレコードを超えている場合、現在使用可能なレコードがない場合)。この場合、最初の引数の値は正当に定義されません。

バインドプロパティの値をこの DataBindingContext に適した値に変換します (可能な場合)。

プログラミング注意事項

通常はアプリケーションから直接呼び出しません。このメソッドは、検証または更新の前にバインドプロパティの値を処理するために DataBinding.get-parsed-value が内部で呼び出します。

value: 解析する値。この値は通常、バインドプロパティの現在の値です。

binding: この変換が行われる DataBinding。このコンテキストに登録されている必要があります。

戻り値

context 内で設定する値、または DataBindingValidationFailure。

説明

このメソッドが変換を実行できない場合、または実行を望まない場合には、コンテキストで使われた入力値をそのまま返すことがあります。ただしこのメソッドが value にエラーがあると判定した場合、そのエラーを説明する DataBindingValidationFailure を生成して返すことがあります。

このメソッドの代わりに指定して使える DataBinding.parse も参照してください。

オーバーライド

このメソッドの既定の実装では、変換は行われず value が返されるだけです。解析機能を提供するサブクラスでは、このメソッドをオーバーライドする必要があります。

登録されている 1 つまたは複数のバインドのターゲットプロパティをリフレッシュします。

...:

リフレッシュする 0 個以上の DataBindingTarget か DataBinding。ターゲットを指定した場合、このコンテキストに登録されているターゲットに存在するすべてのバインドがリフレッシュされます。

ターゲットを指定しない場合、コンテキストに登録されているすべてのバインドがリフレッシュされます。

説明

このメソッドは DataBinding.refresh を呼び出します (詳細を確認してください)。

オーバーライド

通常はオーバーライドされません。

このコンテキストで DataBinding を登録します。

binding: 登録する DataBinding。バインドの DataBinding.context プロパティがこのオブジェクトを参照していること、その DataBinding.target プロパティが null 以外の値であることが必要です。

プログラミング注意事項

このメソッドは通常 DataBinding の実装で呼び出されます。アプリケーションではこのメソッドを直接呼び出さず、代わりに DataBinding.context または DataBinding.auto-register? プロパティを設定してください。

説明

このコンテキストで binding が既に存在する場合、このメソッドでは何も行われません。

登録処理が完了した後で、このメソッドはターゲットを初期化するために DataBinding.refresh を呼び出すことに注意してください。

オーバーライド

サブクラスでは、登録するバインドがこのコンテキストに適していることを確認できるようにこのメソッドをオーバーライドすることをお勧めします。

実装では、このメソッドのスーパー実装を必ず呼び出してください。

バインドで refresh、update または validate 操作が完了した後で呼び出されます。

binding: 操作が完了した DataBinding。このコンテキストに登録されている必要があります。

プログラミング注意事項

通常はアプリケーションから直接呼び出しません。このメソッドは、DataBinding.refresh、DataBindingContext.validate および DataBindingContext.update が内部で呼び出します。

オーバーライド

このメソッドの基本実装では何も行われません。サブクラスではこのクラスをオーバーライドして、バインドとバインドオブジェクトの状態変化に応答できるようにします。

このメソッドは検証結果に応答する場合に役立ちます。特に、このメソッドで DataBinding.validation-failure プロパティを調べられる点に注目してください。検証への応答については、以下の点を考慮します。

ディスプレイ内で持続性のある変更を行い、ターゲットの有効性をユーザーに通知します。(たとえば、ターゲットを「ハイライト表示」の色で設定したり、隣接する領域にエラーの説明を表示します。)このような持続性を持つ変更は、validation-failure プロパティが null であると判定されたときに元に戻すこともできます。
null 以外の validation-failure に対し、データを再送信または再検証して応答します。この場合、無限ループが起こらないように特に注意してください。
DataBinding.refresh を呼び出して不正な値をフラッシュします。validation-failure が null 以外でも安全であると考えられることができる点に注意してください。これは、DataBinding.refresh が検証エラーを常にクリアするためです。

特定バインドの validation-failure が、1 つの更新または検証で生成された DataBindingValidationFailure の大きな階層の一部分である可能性があります。この場合、コンテキストで複数のポップアップメッセージ (または他の割り込み警告) が生成されないように注意してください。

複数検証の失敗の詳細については、DataBindingMultipleValidationFailure と DataBindingValidationFailure.parent を参照してください。

このコンテキストから DataBinding を登録解除します。

binding: 登録解除する DataBinding。

プログラミング注意事項

このメソッドは通常 DataBinding の実装で呼び出されます。アプリケーションではこのメソッドを直接呼び出さず、代わりに DataBinding.context と DataBinding.auto-register? プロパティを直接設定してください。

説明

このコンテキストで binding がまだ登録されていない場合、このメソッドでは何も行われません。

オーバーライド

このメソッドの実装では、必ずスーパー実装を呼び出してください。

登録されている１つまたは複数のバインドのターゲットプロパティからコンテキストを更新します。

...:

更新する 0 個以上の DataBindingTarget か DataBinding。ターゲットを指定した場合、このコンテキストに登録されているターゲットに存在し、allow-update? が true のすべてのバインドが含まれます。

ターゲットを指定しない場合、pending-update? が true のすべてのバインドが使われます。

このコンテキストに登録されていないバインド、または allow-update? が true でないバインドが明示的に指定された場合はエラーになります。

戻り値

DataBindingValidationFailure または null。

プログラミング注意事項

アプリケーションで使用します。一般的な使用法では、[送信] ボタンによる ValueChanged または Action イベントなどのイベントハンドラからこのメソッドを呼び出します。

DataBindingTarget.update-data-binding も参照してください。これはこのメソッドを呼び出すだけですが、シングルバインドを更新するためのより便利な構文を提供しています。

説明

指定されたバインドで DataBindingValidationFailure が発生すると、これを返す前にバインドの DataBinding.validation-failure を設定します。

DataBindingMultipleValidationFailure が返される場合、このメソッドの特定バインド指定に関するエラーが含まれている可能性があります。このようなエラーはすべて、1 つのバインドに対して 1 つの「ルート」エラーにグループ化され、返されるオブジェクトの DataBindingMultipleValidationFailure.children プロパティに格納されます。

オーバーライド

通常はオーバーライドしません。代わりにサブクラスでは DataBindingContext.update-internal をオーバーライドします。

登録されている１つまたは複数のバインドのターゲットプロパティからコンテキストを更新します。

...: 更新する 1 つまたは複数の DataBinding。これらのバインドは、allow-update? = true であり、このコンテキストに登録されていることをあらかじめ確認しておく必要があります。

戻り値

DataBindingValidationFailure または null。戻り値の必要条件の詳細は、DataBindingContext.update-internal を参照してください。

プログラミング注意事項

アプリケーションで使用せず、通常は直接呼び出しません。サブクラスではこのメソッドをオーバーライドする必要があります。

オーバーライド

データ更新を許可するサブクラスでは、このメソッドをオーバーライドして更新の実施方法を定義してください。既定の実装ではエラーをスローします。

登録されている 1 つまたは複数のバインドのターゲットプロパティの値を検証します。

...:

検証する 0 個以上の DataBindingTarget か DataBinding。ターゲットを指定した場合、このコンテキストに登録されているターゲットに存在し、allow-update? が true のすべてのバインドが含まれます。

ターゲットを指定しない場合、コンテキスト内で pending-update? が true であるすべてのバインドが使われます。

このコンテキストに登録されていないバインド、または allow-update? が true でないバインドが明示的に指定された場合はエラーになります。

戻り値

DataBindingValidationFailure または null。

プログラミング注意事項

アプリケーションで使用します。一般的な使用法では、[確認] ボタンによる ValueChanged または Action イベントなどのイベントハンドラからこのメソッドを呼び出します。

DataBindingTarget.validate-data-binding も参照してください。これはこのメソッドを呼び出すだけですが、シングルバインドを検証するためのより便利な構文を提供しています。

説明

指定されたバインドで DataBindingValidationFailure が発生すると、これを返す前にバインドの DataBinding.validation-failure を設定します。

オーバーライド

通常はオーバーライドしません。代わりにサブクラスでは DataBindingContext.validate-internal をオーバーライドします。

登録されている 1 つまたは複数のバインドのターゲットプロパティを検証します。

...: 検証する 1 つまたは複数の DataBinding。これらのバインドは、allow-update? = true であり、このコンテキストに登録されていることをあらかじめ確認しておく必要があります。

戻り値

DataBindingValidationFailure または null。戻り値の必要条件の詳細は、DataBindingContext.validate-internal を参照してください。

プログラミング注意事項

アプリケーションで使用せず、通常は直接呼び出しません。サブクラスではこのメソッドをオーバーライドする必要があります。

オーバーライド

データ更新を許可するサブクラスでは、このメソッドをオーバーライドして検証の実施方法を定義してください。既定の実装ではエラーを返します。