Input Pointers

2017-07-11T11:32:33Z

Mtorni: Note about LaserPointer example requiring release past 2.0.700

An input pointer is [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events#term_pointer any kind of pointing device] which presses, hovers, or both. A mouse, a finger and a stylus are the three main ones. They are related to the (draft) [https://w3c.github.io/pointerevents/ W3C Pointer Events specification]. Here's some specific notes about the input pointers available in PowerUI.

== Mouse Input ==

PowerUI assumes that only a desktop platform will have a mouse. A [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1MousePointer.html MousePointer] is created when it's running on a desktop and [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db PowerUI.Input.CreateSystemMouse] is true ''(the default)''. If your project doesn't use a mouse pointer on a desktop platform (it's [[Virtual Reality Cameras|virtual reality]] for example), you'd remove it by setting [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db CreateSystemMouse] to false in an Awake method.

== Touch and Stylus Input ==

PowerUI handles multi-touch input by default on any platform which supports it. It will automatically stack with a mouse input on desktops which also have touchscreens. Each time a new touch is detected, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1FingerPointer.html FingerPointer] or a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1StylusPointer.html StylusPointer] is created. They fire the various [https://developer.mozilla.org/en-US/docs/Web/API/Touch_events touch events] as well as [https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent mouse events].

All pointers are [https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/isPrimary primary] (which means they all fire those mouse events too).

== Virtual Reality ==

PowerUI has a custom input pointer, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1CameraPointer.html CameraPointer], for virtual reality. See [[Virtual Reality Cameras|the article]] relating to virtual reality camera's. Alternatively here's a (rough!) laser pointer input example. Just add it to your project and see the notes below on how to e.g. add it and make it click:

<syntaxhighlight lang='csharp'>
using System;
using UnityEngine;

/// <summary>A laser pointer which fires an input ray from e.g. a 3D hand.</summary>
/// NOTE: PowerUI.InputPointer.Raycast is defined in PowerUI git master, not in releases at least up to 2.0.700
public class LaserPointer : PowerUI.InputPointer{

public Transform Transform;
/// <summary>True if UI's move around.</summary>
public bool MovingUIs;

/// <summary>Setup a laser pointer from the given transform (e.g. a hand object).</summary>
public LaserPointer(Transform transform):this(transform,true){}

/// <summary>Setup a laser pointer from the given transform (e.g. a hand object).</summary>
/// <param name='movingUIs'>Set this to true if your WorldUI's move around.
/// Setting it to false is a small performance saving. If you're not sure, just use true.</param>
public LaserPointer(Transform transform, bool movingUIs){
Transform = transform;
MovingUIs = movingUIs;

// It won't interact with the main UI so just put it offscreen to skip checking entirely:
ScreenX = ScreenY = -1000f;

}

public override bool Raycast(out RaycastHit hit, Camera cam, Vector2 screenPoint){

// Fire off your ray in whatever your pointers direction is; we'll use transform.forward here.
// ('forward' is +ve z):
Ray ray = new Ray(Transform.position, Transform.forward);

return Physics.Raycast(theRay, out hit);
}

public override bool Relocate(out Vector2 delta){

// We can just ignore delta (it's for the main UI):
delta = Vector2.zero;

if(MovingUIs){
// Always recompute.
return true;
}

// Transform moved?
if(Transform!=null && Transform.hasChanged){
Transform.hasChanged = false;
return true;
}

// Don't bother recalculating - it's not moved.
// (Always return true if your UI's are moving instead).
return false;
}

}

</syntaxhighlight>

Usage:

<syntaxhighlight lang='csharp'>

// Fires a ray from the given hand object. If your UI's don't move around, use LaserPointer(aHandObject,false) to make a performance gain.
LaserPointer myPointer = new LaserPointer(aHandObject);

// Add it:
myPointer.Add();

// myPointer.LeftDown(); etc to click (see more below)

</syntaxhighlight>

== Define your own ==

If you're doing something more specialised then you can also define your own input pointer. Multiple Wii controllers, for example. This is very straight forward to do - at a minimum you must inherit from InputPointer:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{
}

</syntaxhighlight>

Then to use it, all you need to do is create and add it:

<syntaxhighlight lang="csharp">
MyCustomPointer pointer = new MyCustomPointer();
pointer.Add();
</syntaxhighlight>

It can be clicked etc or have a pressure value like any other pointer. To move it around, set the Position property (Top left corner is 0,0):

<syntaxhighlight lang="csharp">
pointer.Position = new Vector2(100,100);
</syntaxhighlight>

Alternatively you can put your position update logic inside the pointer itself by overriding the Relocate method:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{

public override bool Relocate(out Vector2 positionChange){

// - Get your latest coordinates here -
Vector2 newPosition = Vector2.zero;

// Try moving it (just returns false if your position wasn't different to the current one):
return TryChangePosition(newPosition, out positionChange);
}

}

</syntaxhighlight>

== Making it click ==

If you've got an input pointer and you'd like to click it (or vary its downward pressure), you can either:

* Use the convenience method for mouse up/down events from OnGUI:

<syntaxhighlight lang="csharp">

void OnGUI(){

// Returns true if your pointer actually did something (it went down or up)
// You can also directly pass a UnityEngine.Event too.
bool didSomething = MyPointer.HandleEvent();

}

</syntaxhighlight>

* Call the MyPointer.Down and MyPointer.Up methods (Optionally specifying a [https://docs.unity3d.com/ScriptReference/Event-button.html mouse button ID]):

<syntaxhighlight lang="csharp">

// Mousedown event, left button:
MyPointer.Down(0);

// Which is also the same as:
MyPointer.LeftDown();

// Mouseup event, left button:
MyPointer.Up(0);

// Which is the same as:
MyPointer.LeftUp();

</syntaxhighlight>

* Use SetPressure directly - this is useful if you've got some kind of stylus ''(every other option is just an abstraction of SetPressure)''

<syntaxhighlight lang="csharp">

void Update(){

// Update the pointer pressure:
MyPointer.SetPressure(someVaryingField);

}

</syntaxhighlight>

== Accessing all pointers ==

PowerUI implements various standard API's for accessing pointers:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1TouchEvent.html TouchEvent].touches
* TouchEvent.targetTouches
* TouchEvent.changedTouches
* TouchEvent.identifier
* ''More!''

The non-standard internal ones:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1UIEvent.html#a2daa44fbceddd8510bc2791340a432b4 UIEvent.trigger] - ''MouseEvent, TouchEvent etc; The InputPointer instance this event came from''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a77189cd51fedf33c73759f641c8380ef InputPointer.All] - ''All active pointers (array created on use; Use AllRaw and PointerCount for better performance)''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a731d759f87ece43622fb497b5e3d88b3 InputPointer.PointerCount] - ''The number of actual pointers in the AllRaw pointer set''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#aa76092f569304c8fcf6c3bea1f9612e3 InputPointer.AllRaw] - ''The raw set of pointers. Entries beyond PointerCount are random noise/ undefined.''

== Source locations ==

You'll find the implementations of MousePointer, FingerPointer etc here:

* PowerUI/Source/Engine/Input/

PowerUI - User contributions [en]

Input Pointers