Class: DOM

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:
src/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.

Type:
Properties:
Name Type Description
width number

Document width in pixels.

height number

Document height in pixels.

Source:
src/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 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.

Type:
Properties:
Name Type Description
width number

Viewport width in pixels.

height number

Viewport height in pixels.

Source:
src/utils/DOM.js line 260

<protected, static, readonly> scrollX : number

A cross-browser window.scrollX.

Type:
  • number
Source:
src/utils/DOM.js line 289

<protected, static, readonly> scrollY : number

A cross-browser window.scrollY.

Type:
  • number
Source:
src/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 not Firefox Android), Opera Mobile 16

The properties change dynamically.

Type:
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:
src/utils/DOM.js line 239

Methods

<static> getAspectRatio( [object])

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.

Source:
src/utils/DOM.js line 100
Returns:

The aspect ratio.

Type
number

<static> getBounds(element [, cushion])

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.

Source:
src/utils/DOM.js line 48
Returns:

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

Type
Object | boolean

<static> getOffset(element [, 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.

Source:
src/utils/DOM.js line 20
Returns:
  • A point objet with the offsetX and Y as its properties.
Type
Phaser.Point

<protected, 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'.

Source:
src/utils/DOM.js line 149

<static> inLayoutViewport(element [, cushion])

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.

Source:
src/utils/DOM.js line 128
Returns:

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

Type
boolean

phaser-ce@2.9.2 is on GitHub and NPM

Documentation generated by JSDoc 3.5.4 on 2017-11-09 using Tomorrow.