VRTK_UIPointer

Overview

Provides the ability to interact with UICanvas elements and the contained Unity UI elements within.

Optional Components:

• VRTK_ControllerEvents - The events component to listen for the button presses on. This must be applied on the same GameObject as this script if one is not provided via the Controller parameter.

Script Usage:

• Place the VRTK_UIPointer script on either:
  • The controller script alias GameObject of the controller to emit the UIPointer from (e.g. Right Controller Script Alias).
  • Any other scene GameObject and provide a valid Transform component to the Pointer Origin Transform parameter of this script. This does not have to be a controller and can be any GameObject that will emit the UIPointer.

Script Dependencies:

• A UI Canvas attached to a Unity World UI Canvas.

Inspector Parameters

• Activation Button: The button used to activate/deactivate the UI raycast for the pointer.
• Activation Mode: Determines when the UI pointer should be active.
• Selection Button: The button used to execute the select action at the pointer's target position.
• Click Method: Determines when the UI Click event action should happen.
• Attempt Click On Deactivate: Determines whether the UI click action should be triggered when the pointer is deactivated. If the pointer is hovering over a clickable element then it will invoke the click action on that element. Note: Only works with Click Method = Click_On_Button_Up
• Click After Hover Duration: The amount of time the pointer can be over the same UI element before it automatically attempts to click it. 0f means no click attempt will be made.
• Maximum Length: The maximum length the UI Raycast will reach.
• Attached To: An optional GameObject that determines what the pointer is to be attached to. If this is left blank then the GameObject the script is on will be used.
• Controller Events: The Controller Events that will be used to toggle the pointer. If the script is being applied onto a controller then this parameter can be left blank as it will be auto populated by the controller the script is on at runtime.
• Custom Origin: A custom transform to use as the origin of the pointer. If no pointer origin transform is provided then the transform the script is attached to is used.

Class Variables

• public enum ActivationMethods - Methods of activation.
  • HoldButton - Only activates the UI Pointer when the Pointer button on the controller is pressed and held down.
  • ToggleButton - Activates the UI Pointer on the first click of the Pointer button on the controller and it stays active until the Pointer button is clicked again.
  • AlwaysOn - The UI Pointer is always active regardless of whether the Pointer button on the controller is pressed or not.
• public enum ClickMethods - Methods of when to consider a UI Click action
  • ClickOnButtonUp - Consider a UI Click action has happened when the UI Click alias button is released.
  • ClickOnButtonDown - Consider a UI Click action has happened when the UI Click alias button is pressed.
• public GameObject autoActivatingCanvas - The GameObject of the front trigger activator of the canvas currently being activated by this pointer. Default: null
• public bool collisionClick - Determines if the UI Pointer has collided with a valid canvas that has collision click turned on. Default: false

Class Events

• ActivationButtonPressed - Emitted when the UI activation button is pressed.
• ActivationButtonReleased - Emitted when the UI activation button is released.
• SelectionButtonPressed - Emitted when the UI selection button is pressed.
• SelectionButtonReleased - Emitted when the UI selection button is released.
• UIPointerElementEnter - Emitted when the UI Pointer is colliding with a valid UI element.
• UIPointerElementExit - Emitted when the UI Pointer is no longer colliding with any valid UI elements.
• UIPointerElementClick - Emitted when the UI Pointer has clicked the currently collided UI element.
• UIPointerElementDragStart - Emitted when the UI Pointer begins dragging a valid UI element.
• UIPointerElementDragEnd - Emitted when the UI Pointer stops dragging a valid UI element.

Unity Events

Adding the VRTK_UIPointer_UnityEvents component to VRTK_UIPointer object allows access to UnityEvents that will react identically to the Class Events.

• All C# delegate events are mapped to a Unity Event with the On prefix. e.g. MyEvent -> OnMyEvent.

Event Payload

• VRTK_ControllerReference controllerReference - The reference to the controller that was used.
• bool isActive - The state of whether the UI Pointer is currently active or not.
• GameObject currentTarget - The current UI element that the pointer is colliding with.
• GameObject previousTarget - The previous UI element that the pointer was colliding with.
• RaycastResult raycastResult - The raw raycast result of the UI ray collision.

Class Methods

GetPointerLength/1

public static float GetPointerLength(int pointerId)

• Parameters
  • int pointerId - The pointer ID for the UI Pointer to recieve the length for.
• Returns
  • float - The maximum length the UI Pointer will cast to.

The GetPointerLength method retrieves the maximum UI Pointer length for the given pointer ID.

SetEventSystem/1

public virtual VRTK_VRInputModule SetEventSystem(EventSystem eventSystem)

• Parameters
  • EventSystem eventSystem - The global Unity event system to be used by the UI pointers.
• Returns
  • VRTK_VRInputModule - A custom input module that is used to detect input from VR pointers.

The SetEventSystem method is used to set up the global Unity event system for the UI pointer. It also handles disabling the existing Standalone Input Module that exists on the EventSystem and adds a custom VRTK Event System VR Input component that is required for interacting with the UI with VR inputs.

RemoveEventSystem/0

public virtual void RemoveEventSystem()

• Parameters
  • none
• Returns
  • none

The RemoveEventSystem resets the Unity EventSystem back to the original state before the VRTK_VRInputModule was swapped for it.

PointerActive/0

public virtual bool PointerActive()

• Parameters
  • none
• Returns
  • bool - Returns true if the ui pointer should be currently active.

The PointerActive method determines if the ui pointer beam should be active based on whether the pointer alias is being held and whether the Hold Button To Use parameter is checked.

IsActivationButtonPressed/0

public virtual bool IsActivationButtonPressed()

• Parameters
  • none
• Returns
  • bool - Returns true if the activation button is active.

The IsActivationButtonPressed method is used to determine if the configured activation button is currently in the active state.

IsSelectionButtonPressed/0

public virtual bool IsSelectionButtonPressed()

• Parameters
  • none
• Returns
  • bool - Returns true if the selection button is active.

The IsSelectionButtonPressed method is used to determine if the configured selection button is currently in the active state.

ValidClick/2

public virtual bool ValidClick(bool checkLastClick, bool lastClickState = false)

• Parameters
  • bool checkLastClick - If this is true then the last frame's state of the UI Click button is also checked to see if a valid click has happened.
  • bool lastClickState - This determines what the last frame's state of the UI Click button should be in for it to be a valid click.
• Returns
  • bool - Returns true if the UI Click button is in a valid state to action a click, returns false if it is not in a valid state.

The ValidClick method determines if the UI Click button is in a valid state to register a click action.

GetOriginPosition/0

public virtual Vector3 GetOriginPosition()

• Parameters
  • none
• Returns
  • Vector3 - A Vector3 of the pointer transform position

The GetOriginPosition method returns the relevant transform position for the pointer based on whether the pointerOriginTransform variable is valid.

GetOriginForward/0

public virtual Vector3 GetOriginForward()

• Parameters
  • none
• Returns
  • Vector3 - A Vector3 of the pointer transform forward

The GetOriginPosition method returns the relevant transform forward for the pointer based on whether the pointerOriginTransform variable is valid.

Example

VRTK/Examples/034_Controls_InteractingWithUnityUI uses the VRTK_UIPointer script on the right Controller to allow for the interaction with Unity UI elements using a Simple Pointer beam. The left Controller controls a Simple Pointer on the headset to demonstrate gaze interaction with Unity UI elements.