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 theController
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 thePointer 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 actionClickOnButtonUp
- 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
- Returnstrue
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
- Returnstrue
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
- Returnstrue
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
- Returnstrue
if the UI Click button is in a valid state to action a click, returnsfalse
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.
Updated less than a minute ago