CrossBrowdy API documentation

Namespace: CB_Screen

CB_Screen

Static class to manage the screen. It will return itself if it is tried to be instantiated. It can use detect-zoom and NoSleep.js.

Source:

Methods

<static> focus()

Sets the focus to the main window (if possible).

Source:

<static> getAvailableHeight() → {number}

Gets the current available screen height (vertical resolution). Uses the window.screen.availHeight property internally, when possible.

Source:
Returns:

Returns the current available screen height (vertical resolution) in pixels.

Type
number

<static> getAvailableHeightPrevious() → {number}

Gets the previous available screen height (vertical resolution). Useful when the resolution (screen size and/or orientation) changed. Uses the window.screen.availHeight property internally, when possible.

Source:
Returns:

Returns the previous available screen height (vertical resolution) in pixels.

Type
number

<static> getAvailableWidth() → {number}

Gets the current available screen width (horizontal resolution). Uses the window.screen.availWidth property internally, when possible.

Source:
Returns:

Returns the current available screen width (horizontal resolution) in pixels.

Type
number

<static> getAvailableWidthPrevious() → {number}

Gets the previous available screen width (horizontal resolution). Useful when the resolution (screen size and/or orientation) changed. Uses the window.screen.availWidth property internally, when possible.

Source:
Returns:

Returns the previous available screen width (horizontal resolution) in pixels.

Type
number

<static> getColorDepth() → {number}

Gets the current color depth. Uses the window.screen.colorDepth property internally, when possible.

Source:
Returns:

Returns the current color depth.

Type
number

<static> getHeight() → {number}

Gets the current screen height (vertical resolution). Uses the window.screen.height property internally, when possible.

Source:
Returns:

Returns the current screen height (vertical resolution) in pixels.

Type
number

<static> getHeightPrevious() → {number}

Gets the previous screen height (vertical resolution). Calculated through the window.screen.height property internally, when possible. Useful when the resolution (screen size and/or orientation) changed.

Source:
Returns:

Returns the previous screen height (vertical resolution) in pixels.

Type
number

<static> getOrientation() → {string}

Gets the current orientation from the screen orientation object of the Screen Orientation API.

Source:
Returns:

Returns a string with the current orientation from the screen orientation object of the Screen Orientation API. If cannot be found, it will return "landscape-primary" as default.

Type
string

<static> getOrientationObject() → {Object}

Gets the screen orientation object of the Screen Orientation API.

Source:
Returns:

Returns the screen orientation object of the Screen Orientation API.

Type
Object

<static> getPixelRatio() → {number}

Gets the current pixel ratio of the screen (main window). Uses detect-zoom internally.

Source:
To Do:
  • Find a better and more-compatible way to detect pixel ratio which supports as many web clients as possible.
Returns:

Returns the current pixel ratio of the screen (main window). Default pixel ratio is 1 (one) even when it fails.

Type
number

<static> getPixelRatioPrevious() → {number}

Gets the previous pixel ratio of the screen (main window). Useful when the zoom/pixel-ratio changed. Uses detect-zoom internally.

Source:
To Do:
  • Find a better and more-compatible way to detect pixel ratio which supports as many web clients as possible.
Returns:

Returns the previous pixel ratio of the screen (main window). Default previous pixel ratio is 0 (zero) even when it fails.

Type
number

<static> getScrollLeft() → {number|null}

Gets the current scroll left position (horizontal scroll) of the screen (main window). Uses the CB_Elements.getScrollLeftById function internally.

Source:
Returns:

Returns the current scroll left position (horizontal scroll) of the screen (main window). It could return null if something fails.

Type
number | null

<static> getScrollTop() → {number|null}

Gets the current scroll top position (vertical scroll) of the screen (main window). Uses the CB_Elements.getScrollTopById function internally.

Source:
Returns:

Returns the current scroll top position (vertical scroll) of the screen (main window). It could return null if something fails.

Type
number | null

<static> getWidth() → {number}

Gets the current screen width (horizontal resolution). Uses the window.screen.width property internally, when possible.

Source:
Returns:

Returns the current screen width (horizontal resolution) in pixels.

Type
number

<static> getWidthPrevious() → {number}

Gets the previous screen width (horizontal resolution). Calculated through the window.screen.width property internally, when possible. Useful when the resolution (screen size and/or orientation) changed.

Source:
Returns:

Returns the previous screen width (horizontal resolution) in pixels.

Type
number

<static> getWindowHeight() → {number}

Gets the current window height (vertical resolution). Internally, uses the window.innerHeight if possible and fallbacks to document.documentElement.clientHeight or document.body.clientHeight property otherwise, when possible.

Source:
Returns:

Returns the current window height (vertical resolution) in pixels.

Type
number

<static> getWindowHeightPrevious() → {number}

Gets the previous window height (vertical resolution). Useful when the resolution (screen size and/or orientation) or window size changed. Internally, uses the window.innerHeight if possible and fallbacks to document.documentElement.clientHeight or document.body.clientHeight property otherwise, when possible.

Source:
Returns:

Returns the previous window height (vertical resolution) in pixels.

Type
number

<static> getWindowWidth() → {number}

Gets the current window width (horizontal resolution). Internally, uses the window.innerWidth if possible and fallbacks to document.documentElement.clientWidth or document.body.clientWidth property otherwise, when possible.

Source:
Returns:

Returns the current window width (horizontal resolution) in pixels.

Type
number

<static> getWindowWidthPrevious() → {number}

Gets the previous window width (horizontal resolution). Useful when the resolution (screen size and/or orientation) or window size changed. Internally, uses the window.innerWidth if possible and fallbacks to document.documentElement.clientWidth or document.body.clientWidth property otherwise, when possible.

Source:
Returns:

Returns the previous window width (horizontal resolution) in pixels.

Type
number

<static> getZoom() → {number}

Gets the current zoom level of the screen (main window). Uses detect-zoom internally.

Source:
To Do:
  • Find a better and more-compatible way to detect zoom which supports as many web clients as possible.
Returns:

Returns the current zoom level of the screen (main window). Default zoom level is 1 (one) even when it fails.

Type
number

<static> getZoomPrevious() → {number}

Gets the previous zoom level of the screen (main window). Useful when the zoom changed. Uses detect-zoom internally.

Source:
Returns:

Returns the previous zoom level of the screen (main window). Default previous zoom level is 0 (zero) even when it fails.

Type
number

<static> isFocused() → {boolean}

Tells whether the main window is focused or not.

Source:
Returns:

Returns whether the main window is focused or not.

Type
boolean

<static> isFullScreen( [allowedWidthMarginPercentage] [, allowedHeightMarginPercentage]) → {boolean}

Tells whether we are in full screen mode or not. Uses the Fullscreen API and fallbacks to other methods internally, including NW.js (formerly node-webkit) and Electron (Electron.js) ones, when not available.

Parameters:
Name Type Argument Default Description
allowedWidthMarginPercentage number <optional>
 CB_Configuration.CrossBase.CB_Screen_isFullScreen_ALLOWED_WIDTH_MARGIN_PERCENTAGE

Allowed width margin, in percentage, of the total screen available to detect whether it is in full screen or not. Needed by old web clients without Fullscreen API support, mainly.
allowedHeightMarginPercentage number <optional>
 CB_Configuration.CrossBase.CB_Screen_isFullScreen_ALLOWED_HEIGHT_MARGIN_PERCENTAGE

Allowed height margin, in percentage, of the total screen available to detect whether it is in full screen or not. Needed by old web clients without Fullscreen API support, mainly.
Source:
Returns:

Returns whether we are in full screen mode or not.

Type
boolean

<static> isFullScreenAPICompatible() → {boolean}

Tells whether the web client is compatible with the FullScreen API or not.

Source:
Returns:

Returns whether the web client is compatible with the FullScreen API or not.

Type
boolean

<static> isLandscape() → {boolean}

Tells whether the screen (main window) is in landscape position.

Source:
Returns:

Returns whether the screen is in landscape position.

Type
boolean

<static> isVisible() → {boolean}

Tells whether the main window is visible or not.

Source:
Returns:

Returns whether the main window is visible or not.

Type
boolean

<static> keepAwake( [callbackOk] [, callbackError]) → {boolean}

Keeps the screen awake and prevents it from turning off. Uses different methods internally: Apache Cordova's Insomnia plugin, Standby API, Mozilla's Wake Lock API, new W3C's Wake Lock API, old W3C's Wake Lock API, NoSleep.js library (it should be activated by an event fired by the user as onclick or ontouchstart, etc.)...

Parameters:
Name Type Argument Description
callbackOk function <optional>

Function that will be called if the action has been performed successfully, without parameters.
callbackError function <optional>

Function that will be called if the action has not been performed successfully, without parameters.
Source:
To Do:
  • Pay attention since many internal functions as the new W3C's Wake Lock API are still experimental and not well-tested.
Returns:

If it uses the new W3C's Wake Lock API internally, it will return a Promise. Otherwise, it will return a boolean depending on whether the internal method has been called successfully or not. The fact that the internal method has been called successfully does not mean that the action will perform successfully so it is recommended to relay on the "callbackOk" and "callbackError" functions and ignore this returning value.

Type
boolean

<static> keepAwakeDisable( [callbackOk] [, callbackError]) → {boolean}

Lets the screen sleep again and stops preventing it from turning off. Uses different methods internally: Apache Cordova's Insomnia plugin, Standby API, Mozilla's Wake Lock API, new W3C's Wake Lock API, old W3C's Wake Lock API, NoSleep.js library (it should be activated by an event fired by the user as onclick or ontouchstart, etc.)...

Parameters:
Name Type Argument Description
callbackOk function <optional>

Function that will be called if the action has been performed successfully, without parameters.
callbackError function <optional>

Function that will be called if the action has not been performed successfully, without parameters.
Source:
To Do:
  • Pay attention since many internal functions as the new W3C's Wake Lock API are still experimental and not well-tested.
Returns:

If it uses the new W3C's Wake Lock API internally, it will return a Promise. Otherwise, it will return a boolean depending on whether the internal method has been called successfully or not. The fact that the internal method has been called successfully does not mean that the action will perform successfully so it is recommended to relay on the "callbackOk" and "callbackError" functions and ignore this returning value.

Type
boolean

<static> lockOrientation(orientationMode [, onSuccess] [, onError]) → {boolean}

Function that forces a desired screen orientation. Using the lock function and fallbacks to the lockOrientation function of the Screen Orientation API internally.

Parameters:
Name Type Argument Description
orientationMode 'default' | 'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'

Desired orientation. Internally, "default" and "natural" will be exchanged and "any" will be transformed to "default", depending on the internal function used. Values "default", "any" and "natural" are not recommended because they are not supported in all web clients.
onSuccess function <optional>

Callback function with no parameters that will be called if the orientation has been set successfully.
onError function <optional>

Callback function that will be called if the orientation has not been set successfully. Unique parameter received will be an error object (probably a DOMException, depending on the client) with the error.
Source:
To Do:
  • Transform values of "default", "any" and "natural" to "portrait", "landscape", etc. when the web clients do not support it (calculating current orientation and trying to guess natural/default one, etc.).
Returns:

Returns the same Promise that the lock function returns, if available. Otherwise, returns the same boolean as the lockOrientation function (true if the locking action has been performed successfully), if available. Otherwise, returns false when the Screen Orientation API is not available.

Type
boolean

<static> onFocusChange(callbackFunction [, keepOldFunction])

Sets a function to execute when the screen (main window) focus is changed or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> onFullScreenChange(callbackFunction [, keepOldFunction])

Sets a function to execute when full screen mode is changed (enabled or disabled) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> onOrientationChange(callbackFunction [, keepOldFunction])

Sets a function to execute when the screen (main window) orientation is changed (portrait or landscape) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> onResize(callbackFunction [, keepOldFunction])

Sets a function to execute when the screen (main window) is resized (onResize event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> onResizeOrZoom(callbackFunction [, keepOldFunction])

Sets a function to execute when the screen (main window) is resized or the zoom is changed, or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> onScrollLeft(callbackFunction [, keepOldFunction])

Sets a function to execute when the left scroll position (horizontal scroll) is changed in the screen (main window) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> onScrollTop(callbackFunction [, keepOldFunction])

Sets a function to execute when the top scroll position (vertical scroll) is changed in the screen (main window) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> onVisibilityChange(callbackFunction [, keepOldFunction])

Sets a function to execute when the screen (main window) visibility is changed or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired, with no parameters. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
Source:

<static> setFullScreen( [useFullScreen] [, element] [, allowReload])

Toggles between full screen and normal mode. Uses the Fullscreen API and fallbacks to other methods internally, including NW.js (formerly node-webkit) and Electron (Electron.js) ones, when not available. Recommended to be called through an event fired by the user as onclick or ontouchstart, etc.

Parameters:
Name Type Argument Default Description
useFullScreen boolean <optional>
 true

If set to true, it will try to enable full screen mode. Otherwise, it will try to enable normal mode.
element Element <optional>
 document.documentElement|document.body

Element which we want to use in full screen mode. By default uses the whole document body. Only used when the "useFullScreen" parameter is set to true. If an element is provided, it will use neither NW.js (formerly node-webkit) nor Electron (Electron.js) methods.
allowReload boolean <optional>
 false

If set to true and "useFullScreen" is set to true but it fails to enable full screen normally, it will try to reload the entire current document again in a new bigger window. Useful for very old web clients. Only used when the "useFullScreen" parameter is set to true.
Source:

<static> setOrientation()

Alias for CB_Screen.lockOrientation.

Source:
See:

<static> setViewport( [width] [, height] [, userScalable] [, initialScale] [, minimumScale] [, maximumScale] [, shrinkToFit] [, targetDensityDPI]) → {Node|null}

Sets the Viewport meta tag dynamically with the desired options. If the Viewport meta tag already exists, it will be updated. Otherwise, it will create a new one (and append it to the HEAD tag, if found).

Parameters:
Name Type Argument Default Description
width string | integer <optional>

Desired value for the "width" parameter.
height string | integer <optional>

Desired value for the "height" parameter.
userScalable string | boolean <optional>
 'no'

Desired value for the "user-scalable" parameter.
initialScale number <optional>

Desired value for the "initial-scale" parameter.
minimumScale number <optional>

Desired value for the "minimum-scale" parameter.
maximumScale number <optional>

Desired value for the "maximum-scale" parameter.
shrinkToFit string <optional>

Desired value for the "shrink-to-fit" parameter.
targetDensityDPI string | number <optional>

Desired value for the "target-densitydpi" parameter.
Source:
Returns:

Returns the DOM element which belongs to the Viewport meta tag affected (it will have been just created if no one existed before). If a Viewport meta tag could not be created or modified, returns null.

Type
Node | null

<static> unlockOrientation( [onError]) → {boolean}

Function that unlocks the screen orientation. Using the unlock function and fallbacks to the unlockOrientation function of the Screen Orientation API internally.

Parameters:
Name Type Argument Description
onError function <optional>

Callback function that will be called if the orientation has not been unlocked successfully. Unique parameter received will be an error object (probably a DOMException, depending on the client) with the error.
Source:
Returns:

Returns the same that the unlock function returns (undefined, normally), if available. Otherwise, returns the same boolean as the unlockOrientation function (true if the unlocking action has been performed successfully), if available. Otherwise, returns false when the Screen Orientation API is not available.

Type
boolean

<static> unsetOrientation()

Alias for CB_Screen.unlockOrientation.

Source:
See: