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 World Pointer can be and the UI Pointer also requires a controller to initiate the pointer activation and pointer click states.

It's possible to prevent a world canvas from being interactable with a UI Pointer by setting a tag or applying a class to the canvas and then entering the tag or class name for the UI Pointer to ignore on the UI Pointer inspector parameters.

The simplest way to use the UI Pointer is to attach the script to a game controller within the [CameraRig] 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

• 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.
• Activation Mode: Determines when the UI pointer should be active.
• 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.
• Ignore Canvas With Tag Or Class: A string that specifies a canvas Tag or the name of a Script attached to a canvas and denotes that any world canvases that contain this tag or script will be ignored by the UI Pointer.
• Canvas Tag Or Script List Policy: A specified VRTK_TagOrScriptPolicyList to use to determine whether any world canvases will be acted upon by the UI Pointer. If a list is provided then the 'Ignore Canvas With Tag Or Class' parameter will be ignored.

Class Variables

• public enum ActivationMethods - Methods of activation.
• Hold_Button - Only activates the UI Pointer when the Pointer button on the controller is pressed and held down.
• Toggle_Button - 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.
• Always_On - The UI Pointer is always active regardless of whether the Pointer button on the controller is pressed or not.

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.

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.

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 VRTK_EventSystemVRInput SetEventSystem(EventSystem eventSystem)

• Parameters
• EventSystem eventSystem - The global Unity event system to be used by the UI pointers.
• Returns
• VRTK_EventSystemVRInput - A custom event system input class 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.

SetWorldCanvas/1

public void SetWorldCanvas(Canvas canvas)

• Parameters
• Canvas canvas - The canvas object to initialise for use with the UI pointers. Must be of type WorldSpace.
• Returns
• none

The SetWorldCanvas method is used to initialise a WorldSpace canvas for use with the UI Pointer. This method is called automatically on start for all editor created canvases but would need to be manually called if a canvas was generated at runtime.

PointerActive/0

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

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.