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 - utils/DOM.js, line 18

Members

<static, readonly> documentBounds:Phaser.Rectangle

The size of the document / Layout viewport.

This incorrectly reports the dimensions in IE.

The properties change dynamically.

Name

Type

Description

width

number

Document width in pixels.

height

number

Document height in pixels.

Source - utils/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 myviewport?).

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.

Name

Type

Description

width

number

Viewport width in pixels.

height

number

Viewport height in pixels.

Source - utils/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 - utils/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 - utils/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 notFirefox Android), Opera Mobile 16

The properties change dynamically.

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 - utils/DOM.js, line 239

Methods

<static> getAspectRatio(object)→ {number}

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

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.

number-

The aspect ratio.

Source - utils/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.

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.

Object| boolean-

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

Source - utils/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.

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.

Phaser.Point-

  • A point objet with the offsetX and Y as its properties.

Source - utils/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

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 - utils/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.

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.

boolean-

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

Source - utils/DOM.js, line 128