# 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:
  - CrossBase/audiovisual/image/CB_Screen.js, line 12

### Methods

#### <static> focus()

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

  Source:
    - CrossBase/audiovisual/image/CB_Screen.js, line 647

#### <static> getAvailableHeight() → {number}

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

  Source:
    - CrossBase/audiovisual/image/CB_Screen.js, line 244

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 272

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 228

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 260

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 354

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 188

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 216

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1725

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1691

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 467
  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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 487
  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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 369

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 402

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 172

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 204

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 307

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 342

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 284

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 330

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 436
  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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 455

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 637

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1245

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 873

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 498

  ##### Returns:

  Returns whether the screen is in landscape position.

  Type
    boolean

#### <static> isVisible() → {boolean}

  Tells whether the main window is visible or not.

  Source:
    - CrossBase/audiovisual/image/CB_Screen.js, line 585

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1847
  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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1950
  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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1611
  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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 708

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 829

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 684

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 720

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 817

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 660

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 672

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 696

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 898

#### <static> setOrientation()

  Alias for `CB_Screen.lockOrientation`.

  Source:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1597
  See:
    - `CB_Screen.lockOrientation`

#### <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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1755

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1513

  ##### 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:
    - CrossBase/audiovisual/image/CB_Screen.js, line 1502
  See:
    - `CB_Screen.unlockOrientation`

#### Search results