# Namespace: Orientation

## CB_Device. Orientation

Static class to manage the device's orientation. It will return itself if it is tried to be instantiated.

Source:
  - CrossBase/device/CB_Device.js, line 394
To Do:
  - Normalize more differences between web clients.

### Members

#### <static, readonly> cordova_getCompassConstantly_lastId :integer|null

  Keeps the last watch ID that gets the compass heading constantly using the Apache Cordova's Device Orientation plugin. Used by the `CB_Device.Orientation.cordova_getCompassConstantly` function.

  ##### Type:

  - integer | null
  Source:
    - CrossBase/device/CB_Device.js, line 403

### Methods

#### <static> cordova_getCompass(callbackOk, callbackError) → {undefined|false}

  Gets the compass heading using the Apache Cordova's Device Orientation plugin. Uses "navigator.compass.getCurrentHeading" internally.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callbackOk` | function | The function that will be called when it succeeds getting the compass heading. Following the same rules as in https://github.com/apache/cordova-plugin-device-orientation ("navigator.compass.getCurrentHeading" function).
  `callbackError` | function | The function that will be called if there is any error getting the compass heading. Following the same rules as in https://github.com/apache/cordova-plugin-device-orientation ("navigator.compass.getCurrentHeading" function).

  Source:
    - CrossBase/device/CB_Device.js, line 545
  To Do:
    - Add a function to normalize the event and call it automatically.

  ##### Returns:

  Returns false in the case that the Apache Cordova's Device Orientation plugin is not supported or undefined otherwise.

  Type
    undefined | false

#### <static> cordova_getCompassConstantly( [callbackOkOrId] [, callbackError] [, options]) → {integer|undefined|false}

  Starts or stops getting the compass heading constantly at a regular interval. Uses the Apache Cordova's Device Orientation plugin ("navigator.compass.watchHeading" and "navigator.compass.clearWatch" functions).

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `callbackOkOrId` | function | integer | <optional> | `CB_Device.Orientation.cordova_getCompassConstantly_lastId` | In the case that we want to start getting the compass heading, use a function callback that will be called regularly when the compass heading is gotten successfully (using the "navigator.compass.watchHeading" function). To stop getting the compass heading, use the watch ID that we want to stop (using the "navigator.compass.clearWatch" function). Following the same rules as the first parameter of the "navigator.compass.watchHeading" function (when we want to start watching) or the first parameter of "navigator.compass.clearWatch" function (when we want to stop watching) described in https://github.com/apache/cordova-plugin-device-orientation.
  `callbackError` | function | <optional> |  | Callback that will be called if there is any error getting the compass heading. Only used when we want to start getting the compass heading ("callbackOkOrId" is a function). Following the same rules as the second parameter of the "navigator.compass.watchHeading" function described in https://github.com/apache/cordova-plugin-device-orientation.
  `options` | Object | <optional> |  | Object that represents the desired options. Only used when we want to start getting the compass heading ("callbackOkOrId" is a function). Following the same rules as the third parameter of the "navigator.compass.watchHeading" function described in https://github.com/apache/cordova-plugin-device-orientation.

  Source:
    - CrossBase/device/CB_Device.js, line 562
  To Do:
    - Add a function to normalize the event and call it automatically.
    - Add parameters to keep old callbacks and options.

  ##### Returns:

  Returns false in the case that Apache Cordova's Device Orientation plugin is not supported. In the case that we want to start getting the compass heading ("callbackOkOrId" is a function), it will return the watch ID that has been created. In the case that we want to stop getting the compass heading ("callbackOkOrId" is a watch ID), it will return undefined.

  Type
    integer | undefined | false

#### <static> cordova_getCompassConstantlyDisable( [id]) → {undefined|false}

  Stops getting the compass heading constantly at a regular interval. Uses the Apache Cordova's Device Orientation plugin ("navigator.compass.clearWatch" function).

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `id` | integer | <optional> | `CB_Device.Orientation.cordova_getCompassConstantly_lastId` | The watch ID that we want to stop. Following the same rules as the first parameter of the "navigator.compass.clearWatch" function described in https://github.com/apache/cordova-plugin-device-orientation.

  Source:
    - CrossBase/device/CB_Device.js, line 591
  To Do:
    - Add parameters to keep old callbacks and options.

  ##### Returns:

  Returns false in the case that Apache Cordova's Device Orientation plugin is not supported or undefined otherwise.

  Type
    undefined | false

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

  Tells whether the Apache Cordova's Device Orientation plugin is available or not.

  Source:
    - CrossBase/device/CB_Device.js, line 531

  ##### Returns:

  Type
    boolean

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

  Tells whether the Compass Needs Calibration Event (used by the Device Orientation API or compatible one) is supported or not.

  Source:
    - CrossBase/device/CB_Device.js, line 505

  ##### Returns:

  Type
    boolean

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

  Tells whether the MozOrientation API is supported or not.

  Source:
    - CrossBase/device/CB_Device.js, line 423

  ##### Returns:

  Type
    boolean

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

  Tells whether the Device Orientation Event (used by the Device Orientation API or compatible one) is supported or not.

  Source:
    - CrossBase/device/CB_Device.js, line 412
  To Do:
    - Think about using the "ondeviceorientationabsolute" event.

  ##### Returns:

  Type
    boolean

#### <static> normalizeEvent(e, eventName) → {Event}

  Normalizes the data gotten from the Device Orientation Event produced by different clients to try to match the Device Orientation API and follow always the same rules as much as possible.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `e` | Event | The event object that we want to normalize.
  `eventName` | 'deviceorientation' | 'MozOrientation' | The name of the event that we want to normalize. Case sensitive.

  Source:
    - CrossBase/device/CB_Device.js, line 477
  To Do:
    - Think about using the "deviceorientationabsolute" event.
    - Normalize more differences between web clients.

  ##### Returns:

  Returns the given event object again but normalized (if possible).

  Type
    Event

#### <static> onChange(eventFunction [, keepOldFunction] [, useCapture]) → {undefined|false}

  Sets a function to execute for the Device Orientation Event (used by the Device Orientation API or compatible one) or removes it. Falls back to the MozOrientation API if possible.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `eventFunction` | function | null |  |  | The function that will be called when the event is fired. The event object received will already be normalized by the `CB_Device.Orientation.normalizeEvent` function automatically. Following the same rules as in https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent. 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 or not.
  `useCapture` | float | <optional> | false | Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.

  Source:
    - CrossBase/device/CB_Device.js, line 438
  To Do:
    - Think about using the "deviceorientationabsolute" event.

  ##### Returns:

  Returns false in the case that neither the Device Orientation API (or compatible one) nor the MozOrientation API are supported or undefined otherwise.

  Type
    undefined | false

#### <static> onCompassNeedsCalibration(eventFunction [, keepOldFunction] [, useCapture]) → {undefined|false}

  Sets a function to execute for the Compass Needs Calibration Event (used by the Device Orientation API or compatible one) or removes it.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `eventFunction` | function | null |  |  | The function that will be called when the event is fired. Following the same rules as in https://w3c.github.io/deviceorientation/spec-source-orientation.html#compassneedscalibration. 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 or not.
  `useCapture` | float | <optional> | false | Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.

  Source:
    - CrossBase/device/CB_Device.js, line 519

  ##### Returns:

  Returns false in the case that the Compass Needs Calibration Event is not supported or undefined otherwise.

  Type
    undefined | false

#### Search results