キャプチャイベントは、マウスのキャプチャ状態の変化を知らせます。UI Toolkit には、2 種類のキャプチャイベントがあります。
ある要素がマウスやポインターを捉える (キャプチャ) と、その要素は、ポインティングデバイスがキャプチャを解除するか失うまで、そのポインティングデバイスからイベントを受け取る唯一の要素となります。
例えば、テキストボックス内をクリックすると、テキストボックスがマウスを捉えます。マウスはそのまま画面上を動き回ることができますが、テキストボックスの外でイベントを起こすことはできません。テキストボックスがマウスを捉えている間は、他のイベントは発生しません。ユーザーがテキストボックスの外でマウスボタンを押すと、テキストボックスはマウスのキャプチャを解除します。
| イベント | 説明 | 下降伝播 | 上昇伝播 | キャンセル可能 |
|---|---|---|---|---|
| MouseCaptureEvent | 要素がマウスキャプチャを取得したときに送信されます。 | ✔ | ✔ | |
| MouseCaptureOutEvent | 要素がマウスキャプチャを解除したり、失うときに送信されます。 | ✔ | ✔ | |
| PointerCaptureEvent | 要素がポインターを捉えるときに送信されます。 | ✔ | ✔ | |
| PointerCaptureOutEvent | 要素がポインターを離すときに送信されます。 | ✔ | ✔ |
マウスキャプチャイベントは、物理的なマウス、または物理的なマウスをエミュレートした仮想マウス上のイベントを指します。また、マウスを捉えると、マウスポインターの PointerCaptureEvent が発生します。
要素がマウスキャプチャを解除すると、対応する MouseCaptureOutEvent が発生します。ターゲットは、キャプチャの解除を要求した要素です。
2 つの要素が同時にマウスを捉えることはありません。別のビジュアル要素が MouseCaptureEvent を発すると、元の MouseCaptureEvent を送った要素はキャプチャを失います。また、元の要素で MouseCaptureOutEvent を発生させます。
UI Toolkit では、ポインターイベントがマウスイベントに先行します。ポインタータイプがマウスの場合、キャプチャすると、対応するマウスキャプチャイベントも発生します。ポインターをキャプチャすると、マウスもキャプチャされます。
MouseCaptureEvent は、要素がマウスキャプチャを得るときに送信されます。
target: キャプチャを得る要素
MouseCaptureOutEvent イベントは、要素がマウスキャプチャを解除したり、失ったときに送信されます。
target: キャプチャを失う要素
PointerCaptureEvent イベントは、要素がポインタキャプチャを得るときに送信されます。
target: キャプチャを得る要素
PointerCaptureOutEvent イベントは、要素がポインターキャプチャを解放したり、失ったりしたときに送られます。
target: キャプチャを失う要素
以下の例では、キャプチャイベントの動作と、ポインターのキャプチャと解除を示しています。
この例を実際に見るには、以下を行います。
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;
public class CaptureEventsTestWindow : EditorWindow
{
[MenuItem("Window/UI Toolkit/Capture Events Test Window")]
public static void ShowExample()
{
var wnd = GetWindow<CaptureEventsTestWindow>();
wnd.titleContent = new GUIContent("Capture Events Test Window");
}
private bool m_IsCapturing = false;
public void CreateGUI()
{
// クリックするとコンソールにメッセージを出力するラベルをいくつか加えます。
for (int i = 0; i < 4; i++)
{
Label clickableLabel = new Label($"Label {i} - Click Me!");
clickableLabel.RegisterCallback<MouseDownEvent>((evt) => { Debug.Log($"Clicked on label '{(evt.target as Label).text}'"); });
rootVisualElement.Add(clickableLabel);
}
// ポインターを捉えるラベルを加えます。
Label capturingLabel = new Label("Click here to capture mouse");
capturingLabel.RegisterCallback<MouseDownEvent>((evt) =>
{
if (!m_IsCapturing)
{
capturingLabel.text = "Click here to release mouse";
MouseCaptureController.CaptureMouse(capturingLabel);
m_IsCapturing = true;
}
else
{
capturingLabel.text = "Click here to capture mouse";
MouseCaptureController.ReleaseMouse(capturingLabel);
m_IsCapturing = false;
}
});
rootVisualElement.Add(capturingLabel);
// マウスがキャプチャ/離されるときにメッセージを出力するコールバックを登録します。
rootVisualElement.RegisterCallback<MouseCaptureEvent>((evt) =>
{
Debug.Log("Mouse captured");
});
rootVisualElement.RegisterCallback<MouseCaptureOutEvent>((evt) =>
{
Debug.Log("Mouse captured released");
});
}
}