Version: 2023.2
言語: 日本語
パネルイベント
ツールチップイベント

ポインターイベント

ポインターイベントは、ポインティングデバイスを使った UI インタラクションに対して発生します。マウスイベントと同様に、ポインターイベントは、使用されている入力デバイスに関する追加情報 (ペンの筆圧や傾斜角度など) を提供します。

UI Toolkit では、ポインターイベントが常にマウスイベントに先行します。

ポインターイベントには継続的な位置はありません。また、タッチデバイスから離されたときの固定位置もありません。

PointerStationaryEventPointerCancelEventなどのイベントの一部のポインターイベントは、入力デバイスのオペレーティングシステム (OS) によって発生される条件があります。

すべてのポインターイベントの基本クラスは PointerEventBase です。

イベント 説明  下降伝播 上昇伝播 キャンセル可能
PointerDownEvent ポインターを押すときに送信されます。
PointerUpEvent ポインターをリリースするときに送信されます。
PointerMoveEvent ポインターの状態が変化するときに送信されます。
PointerEnterEvent ポインターがビジュアル要素またはその子孫に入るときに送信されます。
PointerLeaveEvent ポインターがビジュアル要素とその子孫すべてから離れるときに送信されます。
PointerOverEvent ポインターがビジュアル要素に入るときに送信されます。
PointerOutEvent ポインターがビジュアル要素から離れるときに送信されます。
PointerStationaryEvent タッチペンや指などのポインタータイプが、OS で決められた一定時間変化しない場合に送信されます。
PointerCancelEvent ポインターの動作が OS によってキャンセルされるときに送信されます。

固有のプロパティ

altitudeAngle : altitudeAngle には、スタイラスの表面に対する相対的な角度がラジアンで格納されています。値が 0 の場合は、スタイラスが表面に平行であることを示します。π/2 の値は、スタイラスが表面に垂直であることを示します。

azimuthAngle : azimuthAngle には、スタイラスの相対的な x 軸の角度がラジアンで格納されています。値が 0 の場合、スタイラスがデバイスの X 軸に沿っていることを示します。

button : button プロパティは、イベントのトリガーとして押されたマウスボタンを識別する整数を返します。次の表は、整数と関連するマウスボタンの一覧です。

整数 ボタン
0 左ボタン
1 右ボタン
2 中央ボタン

clickCount: clickCount プロパティには、ボタンが押される回数が格納されます。

deltaPosition: deltaPosition プロパティには、前回のマウスイベント時と今回のマウスイベント時のポインター位置の差が格納されます。

deltaTime: deltaTime プロパティには、ポインター値の変化が最後に記録されてからの経過時間が秒単位で格納されます。

localPosition : localPosition プロパティは、ターゲットとなるビジュアル要素に相対的なポインター位置を返します。

modifiers: modifiers プロパティは、現在押されている修飾キーを返します。修飾キーの例としては、Shift キー、Ctrl キー、Alt キーがあります。詳細は MDN ドキュメントの 修飾キーのセクション を参照してください。

pointerId: pointerId プロパティは、イベントを送信するポインターを識別するための整数を返します。

pointerType: pointerType プロパティは、イベントを生成するポインターのタイプを定義する文字列を返します。

position: position プロパティは、スクリーンまたはワールド座標系におけるポインターの位置を返します。

pressedButtons: pressedButton プロパティは、現在押されているマウスボタンの組み合わせを識別する整数を返します。

この数値は、個々のボタンの整数値の合計です (下表参照)。例えば、マウスの右ボタンと中ボタンを同時に押すと、pressedButton の値は 6 になります。

整数 ボタン
1 左ボタン
2 右ボタン
4 中央ボタン

pressure: pressure プロパティは、タッチによって現在加えられている圧力の値を返します。デバイスが圧力を報告しない場合、このプロパティの値は 1.0f です。

radius: radius プロパティは、タッチの半径の推定値を返します。radiusVariance を加えるとタッチの最大半径を得ることができ、引くとタッチの最小半径を得られます。

radiusVariance: radiusVariance プロパティ値は、タッチ半径の精度を決定します。この値を半径に加えるとタッチ半径の最大値が得られ、引くとタッチ半径の最小値が得られます。

tangentialPressure: tangentialPressure プロパティは、タッチペンの追加の感圧制御に適用される圧力を表す float 値を返します。

twist: twist プロパティは、スタイラスの軸周りの回転をラジアンで返します。

イベントリスト

以下のリストは、イベントファミリーの各イベントの名前、説明、ターゲットを示しています。イベントの詳細については、UI Toolkit API を参照してください。

PointerDownEvent

PointerDownEvent は、ビジュアル要素内のポインターを押すときに送信されます。

target : ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下にある一番上の選択可能な要素。

PointerUpEvent

PointerUpEvent は、ビジュアル要素内でポインターを解放すると送信されます。

PointerUpEvent イベントが発生すると、ポインター座標が削除されます。また、ポインターのキャッシュも消去されます。そのため、ポインター位置の記録は残りません。

target : ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下にある一番上の選択可能な要素。

PointerMoveEvent

PointerMoveEvent は、ポインターの状態が変わると発生します。

target : ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下にある一番上の選択可能な要素。

PointerEnterEvent

PointerEnterEvent は、ポインターがビジュアル要素、またはその子孫の 1 つに侵入すると送信されます。

target: ポインターが離れるビジュアル要素 (またはその子孫の 1 つ)。

PointerLeaveEvent

PointerLeaveEvent は、ポインターがビジュアル要素とそのすべての子孫から離れるときに送信されます。例えば、ビジュアル要素に子が含まれている場合、ポインターが親や子の上にないときに、親要素がこのイベントを受け取ります。親要素は、たとえ親要素がポインターの下にある最上位の要素でなくなったとしても、ポインターがその子要素の上にある間は PointerLeaveEvent を受け取りません。代わりに PointerOverEvent を受け取ります。

target: ポインターが離れるビジュアル要素 (またはその子孫の 1 つ)。

PointerOverEvent

PointerOverEvent は、ポインターがビジュアル要素に入るときに送信されます。

target: ポインターの下にあるビジュアル要素。

PointerOutEvent

PointerOutEvent は、ポインターがビジュアル要素から離れるときに送信されます。

target: ポインターが離れるビジュアル要素。

PointerStationaryEvent

PointerStationaryEvent は、ポインターの種類 (タッチペンや指など) が、オペレーティングシステムで決められた一定の時間、変化しなかった場合に送信されます。

target: ポインターを捉えるビジュアル要素、またはポインター下で一番上にある選択可能な要素。

PointerCancelEvent

PointerCancelEvent は、ポインターの操作がオペレーティングシステムによってキャンセルされるときに送信されます。

target: ポインターを捉えるビジュアル要素、またはポインター下で一番上にある選択可能な要素。

以下のコードサンプルでは、黄色のボックスを含む赤のボックスを持つエディターウィンドウを作成します。ポインターがビジュアル要素やその子から離れると、コンソールにメッセージを出力します。PointerOutEventPointerLeaveEvent の動作を示します。

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

  1. Assets > Scripts > Editor の順に選択し、PointerEventsTestWindow.uxml という新しい UXML ファイルを作成します。
  2. 以下の UXML コードをそこにコピーします。
  3. Assets > Scripts > Editor で、PointerEventsTestWindow.cs という名前の新しい C# ファイルを作成します。
  4. コードサンプルを C# スクリプトにコピーします。
  5. エディターツールバーから、Window > UI Toolkit > Pointer Events Test Window を選択します。

UXML コード

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
    <ui:VisualElement style="flex-grow: 1; justify-content: center; align-items: center;">
        <ui:VisualElement name="Red_Box" style="background-color: rgb(183, 34, 46); width: 50%; height: 50%; align-items: center; justify-content: center;">
            <ui:VisualElement name="Yellow_Box" style="width: 175%; height: 50%; background-color: rgb(197, 163, 0);" />
        </ui:VisualElement>
    </ui:VisualElement>
</ui:UXML>

C# コード


using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;
using UnityEditor.UIElements;

public class PointerEventsTestWindow : EditorWindow
{
    [MenuItem("Window/UI Toolkit/Pointer Events Test Window")]
    public static void ShowExample()
    {
        PointerEventsTestWindow wnd = GetWindow<PointerEventsTestWindow>();
        wnd.titleContent = new GUIContent("Pointer Events Test Window");
    }

    public void CreateGUI()
    {
        // UXML をインポート
        VisualTreeAsset visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Scripts/Editor/PointerEventsTestWindow.uxml");
        visualTree.CloneTree(rootVisualElement);

        // 赤いボックスを取得して、ポインターのイベントコールバックを登録
        VisualElement redBox = rootVisualElement.Q("Red_Box");
        redBox.RegisterCallback<PointerOutEvent>(OnPointerOutEvent, TrickleDown.TrickleDown);
        redBox.RegisterCallback<PointerLeaveEvent>(OnPointerLeaveEvent, TrickleDown.TrickleDown);
    }

    private void OnPointerLeaveEvent(PointerLeaveEvent evt)
    {
        Debug.Log($"Pointer LEAVE Event. Target: {(evt.target as VisualElement).name}");
    }

    private void OnPointerOutEvent(PointerOutEvent evt)
    {
        Debug.Log($"Pointer OUT Event. Target: {(evt.target as VisualElement).name}");
    }
}

その他の参考資料

パネルイベント
ツールチップイベント