キャプチャイベント

イベントの参照

Change イベント

キャプチャイベントは、マウスのキャプチャ状態の変化を知らせます。UI Toolkit には、2 種類のキャプチャイベントがあります。

マウスキャプチャイベント
ポインターキャプチャイベント

ある要素がマウスやポインターを捉える (キャプチャ) と、その要素は、ポインティングデバイスがキャプチャを解除するか失うまで、そのポインティングデバイスからイベントを受け取る唯一の要素となります。

例えば、テキストボックス内をクリックすると、テキストボックスがマウスを捉えます。マウスはそのまま画面上を動き回ることができますが、テキストボックスの外でイベントを起こすことはできません。テキストボックスがマウスを捉えている間は、他のイベントは発生しません。ユーザーがテキストボックスの外でマウスボタンを押すと、テキストボックスはマウスのキャプチャを解除します。

イベント	説明	トリクルダウン (下降) 伝播	バブルアップ (上昇) 伝播
MouseCaptureEvent	要素がマウスキャプチャを取得したときに送信されます。	✔	✔
MouseCaptureOutEvent	要素がマウスキャプチャを解除したり、失うときに送信されます。	✔	✔
PointerCaptureEvent	要素がポインターを捉えるときに送信されます。	✔	✔
PointerCaptureOutEvent	要素がポインターを離すときに送信されます。	✔	✔

動作

マウスキャプチャ

マウスキャプチャイベントは、物理的なマウス、または物理的なマウスをエミュレートした仮想マウス上のイベントを指します。また、マウスを捉えると、マウスポインターの PointerCaptureEvent が発生します。

要素がマウスキャプチャを解除すると、対応する MouseCaptureOutEvent が発生します。ターゲットは、キャプチャの解除を要求した要素です。

2 つの要素が同時にマウスを捉えることはありません。別のビジュアル要素が MouseCaptureEvent を発すると、元の MouseCaptureEvent を送った要素はキャプチャを失います。また、元の要素で MouseCaptureOutEvent を発生させます。

ポインターキャプチャ

UI Toolkit では、ポインターイベントがマウスイベントに先行します。ポインタータイプがマウスの場合、キャプチャすると、対応するマウスキャプチャイベントも発生します。ポインターをキャプチャすると、マウスもキャプチャされます。

イベントリスト

MouseCaptureEvent

MouseCaptureEvent は、要素がマウスキャプチャを得るときに送信されます。

target: キャプチャを得る要素

MouseCaptureOutEvent

MouseCaptureOutEvent イベントは、要素がマウスキャプチャを解除したり、失ったときに送信されます。

target: キャプチャを失う要素

PointerCaptureEvent

PointerCaptureEvent イベントは、要素がポインタキャプチャを得るときに送信されます。

target: キャプチャを得る要素

PointerCaptureOutEvent

PointerCaptureOutEvent イベントは、要素がポインターキャプチャを解放したり、失ったりしたときに送られます。

target: キャプチャを失う要素

例

以下の例では、キャプチャイベントの動作と、ポインターのキャプチャと解除を示しています。

この例を実際に見るには、以下を行います。

Assets > Scripts > Editor で、CaptureEventsTestWindow.cs という名前の新しい C# ファイルを作成します。
例を C# スクリプトにコピーします。
エディターツールバーから、Window > UI Toolkit > Capture Events Test Window を選択します。
ダイアログウィンドウ内の様々なラベルをクリックして、コンソールで出力を確認してください。

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");
        });
    }
}

イベントの参照

Change イベント