Packagestarling.events
Classpublic class TouchProcessor
InheritanceTouchProcessor Inheritance Object

The TouchProcessor is used to convert mouse and touch events of the conventional Flash stage to Starling's TouchEvents.

The Starling instance listens to mouse and touch events on the native stage. The attributes of those events are enqueued (right as they are happening) in the TouchProcessor.

Once per frame, the "advanceTime" method is called. It analyzes the touch queue and figures out which touches are active at that moment; the properties of all touch objects are updated accordingly.

Once the list of touches has been finalized, the "processTouches" method is called (that might happen several times in one "advanceTime" execution; no information is discarded). It's responsible for dispatching the actual touch events to the Starling display tree.

Subclassing TouchProcessor

You can extend the TouchProcessor if you need to have more control over touch and mouse input. For example, you could filter the touches by overriding the "processTouches" method, throwing away any touches you're not interested in and passing the rest to the super implementation.

To use your custom TouchProcessor, assign it to the "Starling.touchProcessor" property.

Note that you should not dispatch TouchEvents yourself, since they are much more complex to handle than conventional events (e.g. it must be made sure that an object receives a TouchEvent only once, even if it's manipulated with several fingers). Always use the base implementation of "processTouches" to let them be dispatched. That said: you can always dispatch your own custom events, of course.



Public Properties
 PropertyDefined By
  discardSystemGestures : Boolean
When enabled, all touches that start very close to the window edges are discarded.
TouchProcessor
  multitapDistance : Number
The distance (in points) describing how close two touches must be to each other to be recognized as a multitap gesture.
TouchProcessor
  multitapTime : Number
The time period (in seconds) in which two touches must occur to be recognized as a multitap gesture.
TouchProcessor
  numCurrentTouches : int
[read-only] Returns the number of fingers / touch points that are currently on the stage.
TouchProcessor
  occlusionTest : Function
If this callback returns false, the corresponding touch will have its target set to null, which will prevent the original target from being notified of the touch.
TouchProcessor
  root : DisplayObject
The base object that will be used for hit testing.
TouchProcessor
  simulateMultitouch : Boolean
Indicates if multitouch simulation should be activated.
TouchProcessor
  stage : Stage
[read-only] The stage object to which the touch events are (per default) dispatched.
TouchProcessor
Protected Properties
 PropertyDefined By
  _currentTouches : Vector.<Touch>
The list of all currently active touches.
TouchProcessor
  _queue : Vector.<TouchData>
A vector of arrays with the arguments that were passed to the "enqueue" method (the oldest being at the end of the vector).
TouchProcessor
Public Methods
 MethodDefined By
  
Creates a new TouchProcessor that will dispatch events to the given stage.
TouchProcessor
  
advanceTime(passedTime:Number):void
Analyzes the current touch queue and processes the list of current touches, emptying the queue while doing so.
TouchProcessor
  
Force-end all current touches.
TouchProcessor
  
dispose():void
Removes all event handlers on the stage and releases any acquired resources.
TouchProcessor
  
enqueue(touchID:int, phase:String, globalX:Number, globalY:Number, pressure:Number = 1.0, width:Number = 1.0, height:Number = 1.0):void
Enqueues a new touch or mouse event with the given properties.
TouchProcessor
  
Enqueues an artificial touch that represents the mouse leaving the stage.
TouchProcessor
  
setSystemGestureMargins(topMargin:Number = 10, bottomMargin:Number = 10, leftMargin:Number = 0, rightMargin:Number = 0):void
Configures the margins within which, when a touch is starting, it's considered to be a system gesture (in points).
TouchProcessor
Protected Methods
 MethodDefined By
  
processTouches(touches:Vector.<Touch>, shiftDown:Boolean, ctrlDown:Boolean):void
Dispatches TouchEvents to the display objects that are affected by the list of given touches.
TouchProcessor
Property Detail
_currentTouchesproperty
protected var _currentTouches:Vector.<Touch>

The list of all currently active touches.

_queueproperty 
protected var _queue:Vector.<TouchData>

A vector of arrays with the arguments that were passed to the "enqueue" method (the oldest being at the end of the vector).

discardSystemGesturesproperty 
discardSystemGestures:Boolean

When enabled, all touches that start very close to the window edges are discarded. On mobile, such touches often indicate swipes that are meant to open OS menus. Per default, margins of 10 points at the very top and bottom of the screen are checked. Call 'setSystemGestureMargins()' to adapt the margins in each direction.

The default value is true on mobile, false on desktop.


Implementation
    public function get discardSystemGestures():Boolean
    public function set discardSystemGestures(value:Boolean):void
multitapDistanceproperty 
multitapDistance:Number

The distance (in points) describing how close two touches must be to each other to be recognized as a multitap gesture.


Implementation
    public function get multitapDistance():Number
    public function set multitapDistance(value:Number):void
multitapTimeproperty 
multitapTime:Number

The time period (in seconds) in which two touches must occur to be recognized as a multitap gesture.


Implementation
    public function get multitapTime():Number
    public function set multitapTime(value:Number):void
numCurrentTouchesproperty 
numCurrentTouches:int  [read-only]

Returns the number of fingers / touch points that are currently on the stage.


Implementation
    public function get numCurrentTouches():int
occlusionTestproperty 
occlusionTest:Function

If this callback returns false, the corresponding touch will have its target set to null, which will prevent the original target from being notified of the touch. In other words: the touch is being blocked. Callback format:

function(stageX:Number, stageY:Number):Boolean;

The default value is null.


Implementation
    public function get occlusionTest():Function
    public function set occlusionTest(value:Function):void
rootproperty 
root:DisplayObject

The base object that will be used for hit testing. Per default, this reference points to the stage; however, you can limit touch processing to certain parts of your game by assigning a different object.


Implementation
    public function get root():DisplayObject
    public function set root(value:DisplayObject):void
simulateMultitouchproperty 
simulateMultitouch:Boolean

Indicates if multitouch simulation should be activated. When the user presses ctrl/cmd (and optionally shift), he'll see a second touch cursor that mimics the first. That's an easy way to develop and test multitouch when there's only a mouse available.


Implementation
    public function get simulateMultitouch():Boolean
    public function set simulateMultitouch(value:Boolean):void
stageproperty 
stage:Stage  [read-only]

The stage object to which the touch events are (per default) dispatched.


Implementation
    public function get stage():Stage
Constructor Detail
TouchProcessor()Constructor
public function TouchProcessor(stage:Stage)

Creates a new TouchProcessor that will dispatch events to the given stage.

Parameters
stage:Stage
Method Detail
advanceTime()method
public function advanceTime(passedTime:Number):void

Analyzes the current touch queue and processes the list of current touches, emptying the queue while doing so. This method is called by Starling once per frame.

Parameters

passedTime:Number

cancelTouches()method 
public function cancelTouches():void

Force-end all current touches. Changes the phase of all touches to 'ENDED' and immediately dispatches a new TouchEvent (if touches are present). Called automatically when the app receives a 'DEACTIVATE' event.

dispose()method 
public function dispose():void

Removes all event handlers on the stage and releases any acquired resources.

enqueue()method 
public function enqueue(touchID:int, phase:String, globalX:Number, globalY:Number, pressure:Number = 1.0, width:Number = 1.0, height:Number = 1.0):void

Enqueues a new touch or mouse event with the given properties.

Parameters

touchID:int
 
phase:String
 
globalX:Number
 
globalY:Number
 
pressure:Number (default = 1.0)
 
width:Number (default = 1.0)
 
height:Number (default = 1.0)

enqueueMouseLeftStage()method 
public function enqueueMouseLeftStage():void

Enqueues an artificial touch that represents the mouse leaving the stage.

On OS X, we get mouse events from outside the stage; on Windows, we do not. This method enqueues an artificial hover point that is just outside the stage. That way, objects listening for HOVERs over them will get notified everywhere.

processTouches()method 
protected function processTouches(touches:Vector.<Touch>, shiftDown:Boolean, ctrlDown:Boolean):void

Dispatches TouchEvents to the display objects that are affected by the list of given touches. Called internally by "advanceTime". To calculate updated targets, the method will call "hitTest" on the "root" object.

Parameters

touches:Vector.<Touch> — a list of all touches that have changed just now.
 
shiftDown:Boolean — indicates if the shift key was down when the touches occurred.
 
ctrlDown:Boolean — indicates if the ctrl or cmd key was down when the touches occurred.

setSystemGestureMargins()method 
public function setSystemGestureMargins(topMargin:Number = 10, bottomMargin:Number = 10, leftMargin:Number = 0, rightMargin:Number = 0):void

Configures the margins within which, when a touch is starting, it's considered to be a system gesture (in points). Note that you also need to enable 'ignoreSystemGestures'.

Parameters

topMargin:Number (default = 10)
 
bottomMargin:Number (default = 10)
 
leftMargin:Number (default = 0)
 
rightMargin:Number (default = 0)