UI Toolkit のイベントは、HTML イベント に似ています。イベントが発生すると、ターゲットのビジュアル要素と、ビジュアル要素ツリー内の伝播経路内のすべての要素に送信されます。
イベント処理の流れは以下の通りです。
イベントが伝播経路を移動すると、Event.currentTarget プロパティは、現在そのイベントをハンドルする要素に更新されます。イベントコールバック関数内では、以下の通りです。
Event.currentTarget は、コールバックが登録されるビジュアル要素です。Event.target は、元のイベントが発生するビジュアル要素です。詳しくは、イベントのディスパッチ を参照してください。
イベントコールバックを登録すると、テキストラベル上でマウスをクリックしたときの動作など、既存クラスの個々のインスタンスの動作をカスタマイズできます。イベントのコールバックを登録するには、 RegisterCallback() メソッドを使用して要素に直接コールバックを登録します。
伝搬経路上の各要素 (ターゲットを除く) は、イベントを 2 回受け取ることができます。
デフォルトでは、登録されたコールバックは、ターゲットフェーズとバブリングフェーズの間に実行されます。このデフォルトの動作により、親要素が子要素の後に反応するようになります。
ただし、親要素が子要素より先に反応するようにしたい場合は、以下のように TrickleDown.TrickleDown オプションでコールバックを登録します。
using UnityEngine;
using UnityEngine.UIElements;
...
VisualElement myElement = new VisualElement();
// Register a callback for the trickle-down phase.
myElement.RegisterCallback<PointerDownEvent>(MyCallback, TrickleDown.TrickleDown);
...
これは、ディスパッチャーに、ターゲット段階と降下段階でコールバックを実行するように通知します。
カスタム動作を特定のビジュアル要素に追加するには、以下のようにイベントのコールバックを登録します。
// Register a callback on a pointer down event
myElement.RegisterCallback<PointerDownEvent>(MyCallback);
コールバック関数のシグネチャは以下のようになります。
void MyCallback(PointerDownEvent evt) { /* ... */ }
子要素がイベントをハンドルする要素にコールバックを登録するには、Q() メソッドを使用して子要素を検索し、その要素にコールバックを登録します。
以下の例では、スライダーのポインターアップイベントをハンドルするスライダードラッグコンテナ要素にコールバックを登録します。この場合、スライダー自体ではなく、ドラッグコンテナ要素にコールバックを登録する必要があります。なぜなら、ドラッグコンテナはポインターダウンイベント中にポインターをキャプチャし、次のポインターアップイベントの唯一の受け手になるためです。
var dragContainer = slider.Q("unity-drag-container");
dragContainer.RegisterCallback<PointerUpEvent> ( evt => Debug.Log("PointerUpEvent"));
ノート: 1 つのイベントに対して複数のコールバックを登録できます。ただし、同じコールバック関数を登録できるのは、同じイベントと同じ伝播段階で 1 度だけです。
VisualElement からコールバックを削除するには、 myElement.UnregisterCallback() メソッドを呼び出します。
MonoBehaviour からビジュアル要素にアクセスする方法については、ランタイム UI について を参照してください。
イベントのコールバックと一緒にカスタムデータを送ることができます。カスタムデータを添付するには、呼び出しを拡張してコールバックを登録する必要があります。
以下のコードでは、PointerDownEvent のコールバックを登録し、カスタムデータをコールバック関数に送信しています。
// Send user data along to the callback
myElement.RegisterCallback<PointerDownEvent, MyType>(MyCallbackWithData, myData);
コールバック関数のシグネチャは以下のようになります。
void MyCallbackWithData(PointerDownEvent evt, MyType data) { /* ... */ }
UI コントロールは、value プロパティを使用して内部状態のデータを保持します。
例:
Toggle は、Toggle のオンまたはオフ時に変化するブーリアン値を保持します。IntegerField は、フィールドの整数値を保持します。コントロール値を取得するには、
int val = myIntegerField.value; でコントロールから直接値を取得します。
コントロールから送信された ChangeEvent をリッスンし、変更が発生したときにそれを処理します。以下のようにイベントにコールバックを登録する必要があります。
//RegisterValueChangedCallback is a shortcut for RegisterCallback<ChangeEvent>.
//It constrains the right type of T for any VisualElement that implements an
//INotifyValueChange interface.
myIntegerField.RegisterValueChangedCallback(OnIntegerFieldChange);
コールバック関数のシグネチャは以下のようになります。
void OnIntegerFieldChange(ChangeEvent<int> evt) { /* ... */ }
コントロールの値を変更するには、
myControl.value = myNewValue; で value 変数を直接変更します。これにより、新しい ChangeEvent がトリガーされます。myControl.SetValueWithoutNotify(myNewValue); を使用します。これは新しい ChangeEvent をトリガーしません。詳しくは、変更イベント を参照してください。