| Package | starling.events |
| Class | public class TouchProcessor |
| Inheritance | TouchProcessor  Object |
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 TouchProcessorYou 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.
| Property | Defined 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 | ||
| Property | Defined 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 | ||
| Method | Defined By | ||
|---|---|---|---|
TouchProcessor(stage:Stage) 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 | ||
cancelTouches():void 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 | ||
enqueueMouseLeftStage():void 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 | ||
| Method | Defined 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 | ||
| _currentTouches | property |
protected var _currentTouches:Vector.<Touch>The list of all currently active touches.
| _queue | property |
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).
| discardSystemGestures | property |
discardSystemGestures:BooleanWhen 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.
public function get discardSystemGestures():Boolean public function set discardSystemGestures(value:Boolean):void| multitapDistance | property |
multitapDistance:NumberThe distance (in points) describing how close two touches must be to each other to be recognized as a multitap gesture.
public function get multitapDistance():Number public function set multitapDistance(value:Number):void| multitapTime | property |
multitapTime:NumberThe time period (in seconds) in which two touches must occur to be recognized as a multitap gesture.
public function get multitapTime():Number public function set multitapTime(value:Number):void| numCurrentTouches | property |
numCurrentTouches:int [read-only] Returns the number of fingers / touch points that are currently on the stage.
public function get numCurrentTouches():int| occlusionTest | property |
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.
public function get occlusionTest():Function public function set occlusionTest(value:Function):void| root | property |
root:DisplayObjectThe 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.
public function get root():DisplayObject public function set root(value:DisplayObject):void| simulateMultitouch | property |
simulateMultitouch:BooleanIndicates 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.
public function get simulateMultitouch():Boolean public function set simulateMultitouch(value:Boolean):void| stage | property |
stage:Stage [read-only] The stage object to which the touch events are (per default) dispatched.
public function get stage():Stage| TouchProcessor | () | Constructor |
public function TouchProcessor(stage:Stage)Creates a new TouchProcessor that will dispatch events to the given stage.
Parametersstage:Stage |
| advanceTime | () | method |
public function advanceTime(passedTime:Number):voidAnalyzes 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():voidForce-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():voidRemoves 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):voidEnqueues 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():voidEnqueues 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):voidDispatches 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):voidConfigures 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) |