Phaser 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 - 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.

  ##### Properties:

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

### 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 - 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.

  ##### 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 - 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.

  ##### 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 - 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

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

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