Discover
Learn
Get
Create
Community
Login
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. DOM

new DOM()

DOM utility class.

Provides a useful Window and Element functions as well as cross-browser compatibility buffer.

Some code originally derived from verge. Some parts were inspired by the research of Ryan Van Etten, released under MIT License 2013.

Source code: system/DOM.js (Line 18)

Public Properties

<static, readonly> documentBounds : Phaser.Rectangle

The size of the document / Layout viewport.

This incorrectly reports the dimensions in IE.

The properties change dynamically.

Properties:
Name Type Description
width number

Document width in pixels.
height number

Document height in pixels.
Source code: system/DOM.js (Line 274)

<static, readonly> layoutBounds : Phaser.Rectangle

The bounds of the Layout viewport, as discussed in A tale of two viewports — part two; but honoring the constraints as specified applicable viewport meta-tag.

The bounds returned are not guaranteed to be fully aligned with CSS media queries (see What size is my viewport?).

This is not representative of the Visual bounds: in particular the non-primary axis will generally be significantly larger than the screen height on mobile devices when running with a constrained viewport.

The properties change dynamically.

Properties:
Name Type Description
width number

Viewport width in pixels.
height number

Viewport height in pixels.
Source code: system/DOM.js (Line 260)

<internal, static, readonly> scrollX : number

A cross-browser window.scrollX.

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

<internal, static, readonly> scrollY : number

A cross-browser window.scrollY.

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

<static, readonly> visualBounds : Phaser.Rectangle

The bounds of the Visual viewport, as discussed in A tale of two viewports — part one with one difference: the viewport size excludes scrollbars, as found on some desktop browsers.

Supported mobile: iOS/Safari, Android 4, IE10, Firefox OS (maybe not Firefox Android), Opera Mobile 16

The properties change dynamically.

Properties:
Name Type Description
x number

Scroll, left offset - eg. "scrollX"
y number

Scroll, top offset - eg. "scrollY"
width number

Viewport width in pixels.
height number

Viewport height in pixels.
Source code: system/DOM.js (Line 239)

Public Methods

<static> getAspectRatio(object) → {number}

Get the Visual viewport aspect ratio (or the aspect ratio of an object or element)

Parameters
Name Type Argument Default Description
object DOMElement | Object <optional>
 (visualViewport)

The object to determine the aspect ratio for. Must have public width and height properties or methods.
Returns
number -

The aspect ratio.

Source code: system/DOM.js (Line 100)

<static> getBounds(element, cushion) → {Object | boolean}

A cross-browser element.getBoundingClientRect method with optional cushion.

Returns a plain object containing the properties top/bottom/left/right/width/height with respect to the top-left corner of the current viewport. Its properties match the native rectangle. The cushion parameter is an amount of pixels (+/-) to cushion the element. It adjusts the measurements such that it is possible to detect when an element is near the viewport.

Parameters
Name Type Argument Description
element DOMElement | Object

The element or stack (uses first item) to get the bounds for.
cushion number <optional>

A +/- pixel adjustment amount.
Returns
Object | boolean -

A plain object containing the properties top/bottom/left/right/width/height or false if a non-valid element is given.

Source code: system/DOM.js (Line 48)

<static> getOffset(element, point) → {Phaser.Point}

Get the [absolute] position of the element relative to the Document.

The value may vary slightly as the page is scrolled due to rounding errors.

Parameters
Name Type Argument Description
element DOMElement

The targeted element that we want to retrieve the offset.
point Phaser.Point <optional>

The point we want to take the x/y values of the offset.
Returns
Phaser.Point -
  • A point objet with the offsetX and Y as its properties.
Source code: system/DOM.js (Line 20)

<internal, static> getScreenOrientation(primaryFallback)

Returns the device screen orientation.

Orientation values: 'portrait-primary', 'landscape-primary', 'portrait-secondary', 'landscape-secondary'.

Order of resolving:

  • Screen Orientation API, or variation of - Future track. Most desktop and mobile browsers.
  • Screen size ratio check - If fallback is 'screen', suited for desktops.
  • Viewport size ratio check - If fallback is 'viewport', suited for mobile.
  • window.orientation - If fallback is 'window.orientation', works iOS and probably most Android; non-recommended track.
  • Media query
  • Viewport size ratio check (probably only IE9 and legacy mobile gets here..)

See

  • https://w3c.github.io/screen-orientation/ (conflicts with mozOrientation/msOrientation)
  • https://developer.mozilla.org/en-US/docs/Web/API/Screen.orientation (mozOrientation)
  • http://msdn.microsoft.com/en-us/library/ie/dn342934(v=vs.85).aspx
  • https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Testing_media_queries
  • http://stackoverflow.com/questions/4917664/detect-viewport-orientation
  • http://www.matthewgifford.com/blog/2011/12/22/a-misconception-about-window-orientation
Parameters
Name Type Argument Default Description
primaryFallback string <optional>
 (none)

Specify 'screen', 'viewport', or 'window.orientation'.
Internal:
  • This member is internal (protected) and may be modified or removed in the future.
Source code: system/DOM.js (Line 149)

<static> inLayoutViewport(element, cushion) → {boolean}

Tests if the given DOM element is within the Layout viewport.

The optional cushion parameter allows you to specify a distance.

inLayoutViewport(element, 100) is true if the element is in the viewport or 100px near it. inLayoutViewport(element, -100) is true if the element is in the viewport or at least 100px near it.

Parameters
Name Type Argument Description
element DOMElement | Object

The DOM element to check. If no element is given it defaults to the Phaser game canvas.
cushion number <optional>

The cushion allows you to specify a distance within which the element must be within the viewport.
Returns
boolean -

True if the element is within the viewport, or within cushion distance from it.

Source code: system/DOM.js (Line 128)