ポインターイベントは、ポインティングデバイスを使った 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 キーなどがあります。詳細については、MDN ドキュメントの修飾キーのセクションを参照してください。
pointerId: pointerId プロパティは、イベントを送信するポインターを識別するための整数を返します。
pointerType: pointerType プロパティは、イベントを生成するポインターのタイプを定義する文字列を返します。
position: position プロパティは、画面内またはワールド座標系におけるポインターの位置を返します。
pressedButtons: pressedButton プロパティは、現在押されているマウスボタンの組み合わせを識別する整数を返します。
この数値は、個々のボタンの整数値の合計です (下表参照)。例えば、マウスの右ボタンと中ボタンを同時に押すと、pressedButton の値は 6 になります。
| 整数 | ボタン |
|---|---|
| 1 | 左ボタン |
| 2 | 右ボタン |
| 4 | 中央ボタン |
pressure: pressure プロパティは、タッチによって現在加えられている圧力の値を返します。デバイスからの圧力の報告がない場合、このプロパティの値は 1.0f です。
radius: radius プロパティは、タッチの半径の推定値を返します。最大タッチ半径はこれに radiusVariance を追加し、最小タッチ半径はこれから radiusVariance を差し引いて求めます。
radiusVariance: radiusVariance プロパティ値は、タッチ半径の精度を決定します。この値を半径に追加するとタッチ半径の最大値が得られ、引くとタッチ半径の最小値が得られます。
tangentialPressure: tangentialPressure プロパティは、タッチペンの追加の感圧制御に適用される圧力を表す Float 値を返します。
twist: twist プロパティは、タッチペンの軸周りの回転をラジアンで返します。
以下のリストは、イベントファミリーの各イベントの名前、説明、およびターゲットを示しています。イベントの詳細については、UI Toolkit API を参照してください。
PointerDownEvent は、ビジュアル要素内のポインターを押すときに送信されます。
target: ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下の一番上の選択可能な要素。
PointerUpEvent は、ビジュアル要素内でポインターを解放すると送信されます。
PointerUpEvent イベントが発生すると、ポインター座標も削除されます。また、ポインターのキャッシュも消去されるため、ポインターの場所は記録されません。
target: ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下の一番上の選択可能な要素。
PointerMoveEvent は、ポインターの状態が変わると発生します。
target: ポインターのキャプチャを受け取るビジュアル要素。それ以外の場合は、カーソルの下の一番上の選択可能な要素。
PointerEnterEvent は、ポインターがビジュアル要素またはその子孫に入るときに送信されます。
target: ポインターが離れるビジュアル要素 (またはその子孫の 1 つ)。
PointerLeaveEvent は、ポインターがビジュアル要素とその子孫すべてから離れるときに送信されます。例えば、ビジュアル要素に子が含まれている場合、ポインターが親や子の上にないときに、親要素がこのイベントを受け取ります。親要素は、たとえ親要素がポインターの下にある最上位の要素でなくなったとしても、ポインターがその子要素の上にある間は PointerLeaveEvent を受け取らず、代わりに PointerOverEvent を受信します。
target: ポインターが離れるビジュアル要素 (またはその子孫の 1 つ)。
PointerOverEvent は、ポインターがビジュアル要素に入るときに送信されます。
target: ポインターの下にあるビジュアル要素。
PointerOutEvent は、ポインターがビジュアル要素から離れるときに送信されます。
target: ポインターが離れるビジュアル要素。
PointerStationaryEvent は、タッチペンや指などのポインタータイプが、OS で決められた一定時間変化しない場合に送信されます。
target: ポインターをキャプチャするビジュアル要素、またはポインター下で一番上にある選択可能な要素。
PointerCancelEvent は、ポインターの動作が OS によってキャンセルされるときに送信されます。
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()
{
// Import UXML
VisualTreeAsset visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Scripts/Editor/PointerEventsTestWindow.uxml");
visualTree.CloneTree(rootVisualElement);
// Get the red box and register pointer event callbacks
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}");
}
}