VRTK_UIPointer

Overview

The UI Pointer provides a mechanism for interacting with Unity UI elements on a world canvas. The UI Pointer can be attached to any game object the same way in which a Base Pointer can be and the UI Pointer also requires a controller to initiate the pointer activation and pointer click states.

The simplest way to use the UI Pointer is to attach the script to a game controller along with a Simple Pointer as this provides visual feedback as to where the UI ray is pointing.

The UI pointer is activated via the Pointer alias on the Controller Events and the UI pointer click state is triggered via the UI Click alias on the Controller Events.

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.
• Controller: The controller 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.
• Pointer Origin Transform: 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

• 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.

• OnUIPointerElementEnter - Emits the UIPointerElementEnter class event.
• OnUIPointerElementExit - Emits the UIPointerElementExit class event.
• OnUIPointerElementClick - Emits the UIPointerElementClick class event.
• OnUIPointerElementDragStart - Emits the UIPointerElementDragStart class event.
• OnUIPointerElementDragEnd - Emits the UIPointerElementDragEnd class event.

Event Payload

• uint controllerIndex - The index of 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.

Class Methods

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.

SelectionButtonActive/0

public virtual bool SelectionButtonActive()

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

The SelectionButtonActive 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.