ポインターイベントは、ポインティングデバイスを使った UI インタラクションに対して発生します。マウスイベントと同様に、ポインターイベントは、使用されている入力デバイスに関する追加情報 (ペンの筆圧や傾斜角度など) を提供します。
UI Toolkit では、ポインターイベントが常にマウスイベントに先行します。
ポインターイベントには継続的な位置はありません。また、タッチデバイスから離されたときの固定位置もありません。
PointerStationaryEvent や PointerCancelEventなどのイベントの一部のポインターイベントは、入力デバイスのオペレーティングシステム (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 キーなどがあります。
詳細は、修飾キー のセクションを参照してください。
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 は、ビジュアル要素内のポインターを押すときに送信されます。
target : ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下にある一番上の選択可能な要素。
PointerUpEvent は、ビジュアル要素内でポインターを解放すると送信されます。
PointerUpEvent イベントが発生すると、ポインター座標が削除されます。また、ポインターのキャッシュも消去されます。そのため、ポインター位置の記録は残りません。
target : ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下にある一番上の選択可能な要素。
PointerMoveEvent は、ポインターの状態が変わると発生します。
target : ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下にある一番上の選択可能な要素。
PointerEnterEvent は、ポインターがビジュアル要素、またはその子孫の 1 つに侵入すると送信されます。
target: ポインターが離れるビジュアル要素 (またはその子孫の 1 つ)。
PointerLeaveEvent は、ポインターがビジュアル要素とそのすべての子孫から離れるときに送信されます。例えば、ビジュアル要素に子が含まれている場合、ポインターが親や子の上にないときに、親要素がこのイベントを受け取ります。親要素は、たとえ親要素がポインターの下にある最上位の要素でなくなったとしても、ポインターがその子要素の上にある間は PointerLeaveEvent を受け取りません。代わりに PointerOverEvent を受け取ります。
target: ポインターが離れるビジュアル要素 (またはその子孫の 1 つ)。
PointerOverEvent は、ポインターがビジュアル要素に入るときに送信されます。
target: ポインターの下にあるビジュアル要素。
PointerOutEvent は、ポインターがビジュアル要素から離れるときに送信されます。
target: ポインターが離れるビジュアル要素。
PointerStationaryEvent は、ポインターの種類 (タッチペンや指など) が、オペレーティングシステムで決められた一定の時間、変化しなかった場合に送信されます。
target: ポインターを捉えるビジュアル要素、またはポインター下で一番上にある選択可能な要素。
PointerCancelEvent は、ポインターの操作がオペレーティングシステムによってキャンセルされるときに送信されます。
target: ポインターを捉えるビジュアル要素、またはポインター下で一番上にある選択可能な要素。
以下のコードサンプルでは、黄色のボックスを含む赤のボックスを持つエディターウィンドウを作成します。ポインターがビジュアル要素やその子から離れると、コンソールにメッセージを出力します。PointerOutEvent と PointerLeaveEvent の動作を示します。
この例の動作を実際に見るには、以下を行います。
<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>
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}");
}
}