Navigation
These archived docs are for Phaser 2.4.4 Phaser 3 docs can be found on newdocs.phaser.io.
Phaser CE docs can be found on the Phaser CE Documentation site.

Constructor

Phaser. InputHandler

new InputHandler(sprite)

The Input Handler is bound to a specific Sprite and is responsible for managing all Input events on that Sprite.

Parameters
Name Type Description
sprite Phaser.Sprite

The Sprite object to which this Input Handler belongs.

Source code: input/InputHandler.js (Line 14)

Public Properties

allowHorizontalDrag : boolean

Controls if the Sprite is allowed to be dragged horizontally.

Default Value
  • true
Source code: input/InputHandler.js (Line 69)

allowVerticalDrag : boolean

Controls if the Sprite is allowed to be dragged vertically.

Default Value
  • true
Source code: input/InputHandler.js (Line 75)

boundsRect : Phaser.Rectangle

A region of the game world within which the sprite is restricted during drag.

Source code: input/InputHandler.js (Line 161)

boundsSprite : Phaser.Sprite

A Sprite the bounds of which this sprite is restricted during drag.

Source code: input/InputHandler.js (Line 167)

bringToTop : boolean

If true when this Sprite is clicked or dragged it will automatically be bought to the top of the Group it is within.

Source code: input/InputHandler.js (Line 81)

<internal> checked : boolean

A disposable flag used by the Pointer class when performing priority checks.

Internal:
  • This member is internal (protected) and may be modified or removed in the future.
Source code: input/InputHandler.js (Line 36)

consumePointerEvent : boolean

If this object is set to consume the pointer event then it will stop all propagation from this object on. For example if you had a stack of 6 sprites with the same priority IDs and one consumed the event, none of the others would receive it.

Source code: input/InputHandler.js (Line 175)

dragFromCenter : boolean

Is the Sprite dragged from its center, or the point at which the Pointer was pressed down upon it?

Source code: input/InputHandler.js (Line 190)

draggable : boolean

Is this sprite allowed to be dragged by the mouse? true = yes, false = no

Source code: input/InputHandler.js (Line 155)

dragOffset : Phaser.Point

The offset from the Sprites position that dragging takes place from.

Source code: input/InputHandler.js (Line 185)

dragStartPoint : Phaser.Point

The Point from which the most recent drag started from. Useful if you need to return an object to its starting position.

Source code: input/InputHandler.js (Line 195)

enabled : boolean

If enabled the Input Handler will process input requests and monitor pointer activity.

Source code: input/InputHandler.js (Line 30)

game : Phaser.Game

A reference to the currently running game.

Source code: input/InputHandler.js (Line 24)

isDragged : boolean

true if the Sprite is being currently dragged.

Source code: input/InputHandler.js (Line 63)

pixelPerfectAlpha : number

The alpha tolerance threshold. If the alpha value of the pixel matches or is above this value, it's considered a hit.

Default Value
  • 255
Source code: input/InputHandler.js (Line 149)

pixelPerfectClick : boolean

Set to true to use pixel perfect hit detection when checking if the pointer is over this Sprite when it's clicked or touched. The x/y coordinates of the pointer are tested against the image in combination with the InputHandler.pixelPerfectAlpha value. This feature only works for display objects with image based textures such as Sprites. It won't work on BitmapText or Rope. Warning: This is expensive so only enable if you really need it. Use a pixel perfect check when testing for clicks or touches on the Sprite.

Source code: input/InputHandler.js (Line 143)

pixelPerfectOver : boolean

Set to true to use pixel perfect hit detection when checking if the pointer is over this Sprite. The x/y coordinates of the pointer are tested against the image in combination with the InputHandler.pixelPerfectAlpha value. This feature only works for display objects with image based textures such as Sprites. It won't work on BitmapText or Rope. Warning: This is expensive, especially on mobile (where it's not even needed!) so only enable if required. Also see the less-expensive InputHandler.pixelPerfectClick. Use a pixel perfect check when testing for pointer over.

Source code: input/InputHandler.js (Line 133)

priorityID : number

The priorityID is used to determine which game objects should get priority when input events occur. For example if you have several Sprites that overlap, by default the one at the top of the display list is given priority for input events. You can stop this from happening by controlling the priorityID value. The higher the value, the more important they are considered to the Input events.

Source code: input/InputHandler.js (Line 45)

scaleLayer : boolean

EXPERIMENTAL: Please do not use this property unless you know what it does. Likely to change in the future.

Source code: input/InputHandler.js (Line 180)

snapOffset : Phaser.Point

A Point object that contains by how far the Sprite snap is offset.

Source code: input/InputHandler.js (Line 87)

snapOffsetX : number

This defines the top-left X coordinate of the snap grid.

Source code: input/InputHandler.js (Line 117)

snapOffsetY : number

This defines the top-left Y coordinate of the snap grid..

Source code: input/InputHandler.js (Line 123)

snapOnDrag : boolean

When the Sprite is dragged this controls if the center of the Sprite will snap to the pointer on drag or not.

Source code: input/InputHandler.js (Line 93)

snapOnRelease : boolean

When the Sprite is dragged this controls if the Sprite will be snapped on release.

Source code: input/InputHandler.js (Line 99)

snapPoint : Phaser.Point

If the sprite is set to snap while dragging this holds the point of the most recent 'snap' event.

Source code: input/InputHandler.js (Line 200)

snapX : number

When a Sprite has snapping enabled this holds the width of the snap grid.

Source code: input/InputHandler.js (Line 105)

snapY : number

When a Sprite has snapping enabled this holds the height of the snap grid.

Source code: input/InputHandler.js (Line 111)

sprite : Phaser.Sprite

The Sprite object to which this Input Handler belongs.

Source code: input/InputHandler.js (Line 19)

useHandCursor : boolean

On a desktop browser you can set the 'hand' cursor to appear when moving over the Sprite.

Source code: input/InputHandler.js (Line 51)

Public Methods

checkBoundsRect()

Bounds Rect check for the sprite drag

Source code: input/InputHandler.js (Line 1487)

checkBoundsSprite()

Parent Sprite Bounds check for the sprite drag.

Source code: input/InputHandler.js (Line 1537)

checkPixel(x, y, pointer) → {boolean}

Runs a pixel perfect check against the given x/y coordinates of the Sprite this InputHandler is bound to. It compares the alpha value of the pixel and if >= InputHandler.pixelPerfectAlpha it returns true.

Parameters
Name Type Argument Description
x number

The x coordinate to check.

y number

The y coordinate to check.

pointer Phaser.Pointer <optional>

The pointer to get the x/y coordinate from if not passed as the first two parameters.

Returns
boolean -

true if there is the alpha of the pixel is >= InputHandler.pixelPerfectAlpha

Source code: input/InputHandler.js (Line 750)

checkPointerDown(pointer, fastTest) → {boolean}

Checks if the given pointer is both down and over the Sprite this InputHandler belongs to. Use the fastTest flag is to quickly check just the bounding hit area even if InputHandler.pixelPerfectOver is true.

Parameters
Name Type Argument Default Description
pointer Phaser.Pointer
fastTest boolean <optional>
false

Force a simple hit area check even if pixelPerfectOver is true for this object?

Returns
boolean -

True if the pointer is down, otherwise false.

Source code: input/InputHandler.js (Line 674)

checkPointerOver(pointer, fastTest) → {boolean}

Checks if the given pointer is over the Sprite this InputHandler belongs to. Use the fastTest flag is to quickly check just the bounding hit area even if InputHandler.pixelPerfectOver is true.

Parameters
Name Type Argument Default Description
pointer Phaser.Pointer
fastTest boolean <optional>
false

Force a simple hit area check even if pixelPerfectOver is true for this object?

Returns
boolean -
Source code: input/InputHandler.js (Line 712)

destroy()

Clean up memory.

Source code: input/InputHandler.js (Line 400)

disableDrag()

Stops this sprite from being able to be dragged. If it is currently the target of an active drag it will be stopped immediately; also disables any set callbacks.

Source code: input/InputHandler.js (Line 1282)

disableSnap()

Stops the sprite from snapping to a grid during drag or release.

Source code: input/InputHandler.js (Line 1474)

downDuration(pointerId) → {number}

If the pointer is currently over this Sprite this returns how long it has been there for in milliseconds.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
number -

The number of milliseconds the pointer has been pressed down on the Sprite, or -1 if not over.

Source code: input/InputHandler.js (Line 1214)

enableDrag(lockCenter, bringToTop, pixelPerfect, alphaThreshold, boundsRect, boundsSprite)

Allow this Sprite to be dragged by any valid pointer.

When the drag begins the Sprite.events.onDragStart event will be dispatched.

When the drag completes by way of the user letting go of the pointer that was dragging the sprite, the Sprite.events.onDragStop event is dispatched.

For the duration of the drag the Sprite.events.onDragUpdate event is dispatched. This event is only dispatched when the pointer actually changes position and moves. The event sends 5 parameters: sprite, pointer, dragX, dragY and snapPoint.

Parameters
Name Type Argument Default Description
lockCenter boolean <optional>
false

If false the Sprite will drag from where you click it minus the dragOffset. If true it will center itself to the tip of the mouse pointer.

bringToTop boolean <optional>
false

If true the Sprite will be bought to the top of the rendering list in its current Group.

pixelPerfect boolean <optional>
false

If true it will use a pixel perfect test to see if you clicked the Sprite. False uses the bounding box.

alphaThreshold boolean <optional>
255

If using pixel perfect collision this specifies the alpha level from 0 to 255 above which a collision is processed.

boundsRect Phaser.Rectangle <optional>
null

If you want to restrict the drag of this sprite to a specific Rectangle, pass the Phaser.Rectangle here, otherwise it's free to drag anywhere.

boundsSprite Phaser.Sprite <optional>
null

If you want to restrict the drag of this sprite to within the bounding box of another sprite, pass it here.

Source code: input/InputHandler.js (Line 1234)

enableSnap(snapX, snapY, onDrag, onRelease, snapOffsetX, snapOffsetY)

Make this Sprite snap to the given grid either during drag or when it's released. For example 16x16 as the snapX and snapY would make the sprite snap to every 16 pixels.

Parameters
Name Type Argument Default Description
snapX number

The width of the grid cell to snap to.

snapY number

The height of the grid cell to snap to.

onDrag boolean <optional>
true

If true the sprite will snap to the grid while being dragged.

onRelease boolean <optional>
false

If true the sprite will snap to the grid when released.

snapOffsetX number <optional>
0

Used to offset the top-left starting point of the snap grid.

snapOffsetY number <optional>
0

Used to offset the top-left starting point of the snap grid.

Source code: input/InputHandler.js (Line 1446)

globalToLocalX(x)

Warning: EXPERIMENTAL

Parameters
Name Type Description
x number
Source code: input/InputHandler.js (Line 1357)

globalToLocalY(y)

Warning: EXPERIMENTAL

Parameters
Name Type Description
y number
Source code: input/InputHandler.js (Line 1375)

isPixelPerfect() → {boolean}

Is this object using pixel perfect checking?

Returns
boolean -

True if the this InputHandler has either pixelPerfectClick or pixelPerfectOver set to true.

Source code: input/InputHandler.js (Line 461)

justOut(pointerId, delay) → {boolean}

Returns true if the pointer has left the Sprite within the specified delay time (defaults to 500ms, half a second)

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
delay number

The time below which the pointer is considered as just out.

Returns
boolean -
Source code: input/InputHandler.js (Line 1143)

justOver(pointerId, delay) → {boolean}

Returns true if the pointer has entered the Sprite within the specified delay time (defaults to 500ms, half a second)

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
delay number

The time below which the pointer is considered as just over.

Returns
boolean -
Source code: input/InputHandler.js (Line 1126)

justPressed(pointerId, delay) → {boolean}

Returns true if the pointer has touched or clicked on the Sprite within the specified delay time (defaults to 500ms, half a second)

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
delay number

The time below which the pointer is considered as just over.

Returns
boolean -
Source code: input/InputHandler.js (Line 1160)

justReleased(pointerId, delay) → {boolean}

Returns true if the pointer was touching this Sprite, but has been released within the specified delay time (defaults to 500ms, half a second)

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
delay number

The time below which the pointer is considered as just out.

Returns
boolean -
Source code: input/InputHandler.js (Line 1177)

overDuration(pointerId) → {number}

If the pointer is currently over this Sprite this returns how long it has been there for in milliseconds.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
number -

The number of milliseconds the pointer has been over the Sprite, or -1 if not over.

Source code: input/InputHandler.js (Line 1194)

pointerDown(pointerId) → {boolean}

If the Pointer is down this returns true. This only checks if the Pointer is down, not if it's down over any specific Sprite.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
boolean -
  • True if the given pointer is down, otherwise false.
Source code: input/InputHandler.js (Line 505)

pointerDragged(pointerId) → {boolean}

Is this sprite being dragged by the mouse or not?

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
boolean -

True if the pointer is dragging an object, otherwise false.

Source code: input/InputHandler.js (Line 659)

pointerOut(pointerId) → {boolean}

Is the Pointer outside of this Sprite?

Parameters
Name Type Argument Default Description
pointerId integer <optional>
(check all)

The ID number of a Pointer to check. If you don't provide a number it will check all Pointers.

Returns
boolean -

True if the given pointer (if a index was given, or any pointer if not) is out of this object.

Source code: input/InputHandler.js (Line 598)

pointerOver(pointerId) → {boolean}

Is the Pointer over this Sprite?

Parameters
Name Type Argument Default Description
pointerId integer <optional>
(check all)

The ID number of a Pointer to check. If you don't provide a number it will check all Pointers.

Returns
boolean -
  • True if the given pointer (if a index was given, or any pointer if not) is over this object.
Source code: input/InputHandler.js (Line 567)

pointerTimeDown(pointerId) → {number}

A timestamp representing when the Pointer first touched the touchscreen.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
(check all)
Returns
number -
Source code: input/InputHandler.js (Line 537)

pointerTimeOut(pointerId) → {number}

A timestamp representing when the Pointer left the touchscreen.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
number -
Source code: input/InputHandler.js (Line 644)

pointerTimeOver(pointerId) → {number}

A timestamp representing when the Pointer first touched the touchscreen.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
number -
Source code: input/InputHandler.js (Line 629)

pointerTimeUp(pointerId) → {number}

A timestamp representing when the Pointer left the touchscreen.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
number -
Source code: input/InputHandler.js (Line 552)

pointerUp(pointerId) → {boolean}

If the Pointer is up this returns true. This only checks if the Pointer is up, not if it's up over any specific Sprite.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
boolean -
  • True if the given pointer is up, otherwise false.
Source code: input/InputHandler.js (Line 521)

pointerX(pointerId) → {number}

The x coordinate of the Input pointer, relative to the top-left of the parent Sprite. This value is only set when the pointer is over this Sprite.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
number -

The x coordinate of the Input pointer.

Source code: input/InputHandler.js (Line 473)

pointerY(pointerId) → {number}

The y coordinate of the Input pointer, relative to the top-left of the parent Sprite This value is only set when the pointer is over this Sprite.

Parameters
Name Type Argument Default Description
pointerId integer <optional>
0
Returns
number -

The y coordinate of the Input pointer.

Source code: input/InputHandler.js (Line 489)

reset()

Resets the Input Handler and disables it.

Source code: input/InputHandler.js (Line 351)

setDragLock(allowHorizontal, allowVertical)

Restricts this sprite to drag movement only on the given axis. Note: If both are set to false the sprite will never move!

Parameters
Name Type Argument Default Description
allowHorizontal boolean <optional>
true

To enable the sprite to be dragged horizontally set to true, otherwise false.

allowVertical boolean <optional>
true

To enable the sprite to be dragged vertically set to true, otherwise false.

Source code: input/InputHandler.js (Line 1429)

start(priority, useHandCursor) → {Phaser.Sprite}

Starts the Input Handler running. This is called automatically when you enable input on a Sprite, or can be called directly if you need to set a specific priority.

Parameters
Name Type Description
priority number

Higher priority sprites take click priority over low-priority sprites when they are stacked on-top of each other.

useHandCursor boolean

If true the Sprite will show the hand cursor on mouse-over (doesn't apply to mobile browsers)

Returns

The Sprite object to which the Input Handler is bound.

Source code: input/InputHandler.js (Line 252)

startDrag(pointer)

Called by Pointer when drag starts on this Sprite. Should not usually be called directly.

Parameters
Name Type Description
pointer Phaser.Pointer
Source code: input/InputHandler.js (Line 1304)

stop()

Stops the Input Handler from running.

Source code: input/InputHandler.js (Line 380)

stopDrag(pointer)

Called by Pointer when drag is stopped on this Sprite. Should not usually be called directly.

Parameters
Name Type Description
pointer Phaser.Pointer
Source code: input/InputHandler.js (Line 1393)

<internal> update(pointer)

Update.

Parameters
Name Type Description
pointer Phaser.Pointer
Internal:
  • This member is internal (protected) and may be modified or removed in the future.
Source code: input/InputHandler.js (Line 819)

updateDrag(pointer) → {boolean}

Updates the Pointer drag on this Sprite.

Parameters
Name Type Description
pointer Phaser.Pointer
Returns
boolean -
Source code: input/InputHandler.js (Line 1044)

<internal> validForInput(highestID, highestRenderID, includePixelPerfect) → {boolean}

Checks if the object this InputHandler is bound to is valid for consideration in the Pointer move event. This is called by Phaser.Pointer and shouldn't typically be called directly.

Parameters
Name Type Argument Default Description
highestID number

The highest ID currently processed by the Pointer.

highestRenderID number

The highest Render Order ID currently processed by the Pointer.

includePixelPerfect boolean <optional>
true

If this object has pixelPerfectClick or pixelPerfectOver set should it be considered as valid?

Returns
boolean -

True if the object this InputHandler is bound to should be considered as valid for input detection.

Internal:
  • This member is internal (protected) and may be modified or removed in the future.
Source code: input/InputHandler.js (Line 426)