crossbrowdy
Version:
A Multimedia JavaScript framework to create real cross-platform and hybrid game engines, games, emulators, multimedia libraries and apps.
722 lines (610 loc) • 109 kB
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>CrossBrowdy API documentation [printable] Source: CrossBase/device/CB_Device.js</title>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
<link type="text/css" rel="stylesheet" href="styles/site.yeti.css">
</head>
<body style="min-width:800px; overflow-wrap:break-word; word-wrap:break-word; word-break:break-word; line-break:strict; hyphens:none; -webkit-hyphens:none; -moz-hyphens:none;">
<div class="navbar navbar-default navbar-fixed-top ">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand" href="index.html">CrossBrowdy API documentation [printable]</a>
<button class="navbar-toggle" type="button" data-toggle="collapse" data-target="#topNavigation">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<div class="navbar-collapse collapse" id="topNavigation">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="namespaces.list.html" class="dropdown-toggle" data-toggle="dropdown">Namespaces<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="CB_Arrays.html">CB_Arrays</a></li><li><a href="CB_AudioDetector.html">CB_AudioDetector</a></li><li><a href="CB_Client.html">CB_Client</a></li><li><a href="CB_Collisions.html">CB_Collisions</a></li><li><a href="CB_Configuration.html">CB_Configuration</a></li><li><a href="CB_Configuration.CrossBase.html">CB_Configuration.CrossBase</a></li><li><a href="CB_Configuration.CrossBrowdy.html">CB_Configuration.CrossBrowdy</a></li><li><a href="CB_Controllers.html">CB_Controllers</a></li><li><a href="CB_Controllers_Proprietary.html">CB_Controllers_Proprietary</a></li><li><a href="CB_Controllers_Proprietary.WII.html">CB_Controllers_Proprietary.WII</a></li><li><a href="CB_Controllers_Proprietary.WII_U.html">CB_Controllers_Proprietary.WII_U</a></li><li><a href="CB_Device.html">CB_Device</a></li><li><a href="CB_Device.AmbientLight.html">CB_Device.AmbientLight</a></li><li><a href="CB_Device.Battery.html">CB_Device.Battery</a></li><li><a href="CB_Device.Location.html">CB_Device.Location</a></li><li><a href="CB_Device.Motion.html">CB_Device.Motion</a></li><li><a href="CB_Device.Orientation.html">CB_Device.Orientation</a></li><li><a href="CB_Device.Proximity.html">CB_Device.Proximity</a></li><li><a href="CB_Device.Vibration.html">CB_Device.Vibration</a></li><li><a href="CB_Elements.html">CB_Elements</a></li><li><a href="CB_Events.html">CB_Events</a></li><li><a href="CB_Keyboard.html">CB_Keyboard</a></li><li><a href="CB_Keyboard.chars.html">CB_Keyboard.chars</a></li><li><a href="CB_Keyboard.extended.html">CB_Keyboard.extended</a></li><li><a href="CB_Keyboard.keys.html">CB_Keyboard.keys</a></li><li><a href="CB_Modules.html">CB_Modules</a></li><li><a href="CB_Mouse.html">CB_Mouse</a></li><li><a href="CB_Mouse.CursorImage.html">CB_Mouse.CursorImage</a></li><li><a href="CB_Net.html">CB_Net</a></li><li><a href="CB_Net.Fetch.html">CB_Net.Fetch</a></li><li><a href="CB_Net.REST.html">CB_Net.REST</a></li><li><a href="CB_Net.Sockets.html">CB_Net.Sockets</a></li><li><a href="CB_Net.Sockets.SockJS.html">CB_Net.Sockets.SockJS</a></li><li><a href="CB_Net.XHR.html">CB_Net.XHR</a></li><li><a href="CB_Pointer.html">CB_Pointer</a></li><li><a href="CB_Screen.html">CB_Screen</a></li><li><a href="CB_Speaker.html">CB_Speaker</a></li><li><a href="CB_Touch.html">CB_Touch</a></li><li><a href="CB_baseSymbols.html">CB_baseSymbols</a></li>
</ul>
</li>
<li class="dropdown">
<a href="classes.list.html" class="dropdown-toggle" data-toggle="dropdown">Classes<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="CB_AudioFile.html">CB_AudioFile</a></li><li><a href="CB_AudioFileCache.html">CB_AudioFileCache</a></li><li><a href="CB_AudioFileSprites.html">CB_AudioFileSprites</a></li><li><a href="CB_AudioFileSpritesPool.html">CB_AudioFileSpritesPool</a></li><li><a href="CB_AudioFile_API.AAPI.html">CB_AudioFile_API.AAPI</a></li><li><a href="CB_AudioFile_API.ACMP.html">CB_AudioFile_API.ACMP</a></li><li><a href="CB_AudioFile_API.SM2.html">CB_AudioFile_API.SM2</a></li><li><a href="CB_AudioFile_API.WAAPI.html">CB_AudioFile_API.WAAPI</a></li><li><a href="CB_Canvas.html">CB_Canvas</a></li><li><a href="CB_GraphicSprites.html">CB_GraphicSprites</a></li><li><a href="CB_GraphicSpritesScene.html">CB_GraphicSpritesScene</a></li>
</ul>
</li>
<li class="dropdown">
<a href="global.html" class="dropdown-toggle" data-toggle="dropdown">Global<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="global.html#CB_BASE_NAME">CB_BASE_NAME</a></li><li><a href="global.html#CB_CREDITS_DEFAULT">CB_CREDITS_DEFAULT</a></li><li><a href="global.html#CB_NAME">CB_NAME</a></li><li><a href="global.html#CB_OPTIONS">CB_OPTIONS</a></li><li><a href="global.html#CB_VERSION">CB_VERSION</a></li><li><a href="global.html#CB_addCredits">CB_addCredits</a></li><li><a href="global.html#CB_baseToBase">CB_baseToBase</a></li><li><a href="global.html#CB_baseToInt">CB_baseToInt</a></li><li><a href="global.html#CB_br2nl">CB_br2nl</a></li><li><a href="global.html#CB_brToNl">CB_brToNl</a></li><li><a href="global.html#CB_combineArraysOrObjects">CB_combineArraysOrObjects</a></li><li><a href="global.html#CB_combineAutomatically">CB_combineAutomatically</a></li><li><a href="global.html#CB_combineJSON">CB_combineJSON</a></li><li><a href="global.html#CB_combineURIParameters">CB_combineURIParameters</a></li><li><a href="global.html#CB_combineURLParameters">CB_combineURLParameters</a></li><li><a href="global.html#CB_console">CB_console</a></li><li><a href="global.html#CB_copyObject">CB_copyObject</a></li><li><a href="global.html#CB_countDecimalDigits">CB_countDecimalDigits</a></li><li><a href="global.html#CB_countDecimalPart">CB_countDecimalPart</a></li><li><a href="global.html#CB_countDecimals">CB_countDecimals</a></li><li><a href="global.html#CB_countIntegerDigits">CB_countIntegerDigits</a></li><li><a href="global.html#CB_countIntegerPart">CB_countIntegerPart</a></li><li><a href="global.html#CB_credits">CB_credits</a></li><li><a href="global.html#CB_forEach">CB_forEach</a></li><li><a href="global.html#CB_forceString">CB_forceString</a></li><li><a href="global.html#CB_getBase64StringObject">CB_getBase64StringObject</a></li><li><a href="global.html#CB_getCookie">CB_getCookie</a></li><li><a href="global.html#CB_getDatum">CB_getDatum</a></li><li><a href="global.html#CB_getJSONPropertyValue">CB_getJSONPropertyValue</a></li><li><a href="global.html#CB_getLZStringObject">CB_getLZStringObject</a></li><li><a href="global.html#CB_getValueIndex">CB_getValueIndex</a></li><li><a href="global.html#CB_getValuePath">CB_getValuePath</a></li><li><a href="global.html#CB_includeJSFile">CB_includeJSFile</a></li><li><a href="global.html#CB_indexOf">CB_indexOf</a></li><li><a href="global.html#CB_init">CB_init</a></li><li><a href="global.html#CB_intToBase">CB_intToBase</a></li><li><a href="global.html#CB_isArray">CB_isArray</a></li><li><a href="global.html#CB_isEmail">CB_isEmail</a></li><li><a href="global.html#CB_isFileLocal">CB_isFileLocal</a></li><li><a href="global.html#CB_isString">CB_isString</a></li><li><a href="global.html#CB_lastIndexOf">CB_lastIndexOf</a></li><li><a href="global.html#CB_ltrim">CB_ltrim</a></li><li><a href="global.html#CB_nl2br">CB_nl2br</a></li><li><a href="global.html#CB_nlToBr">CB_nlToBr</a></li><li><a href="global.html#CB_numberFormat">CB_numberFormat</a></li><li><a href="global.html#CB_numberOfDecimalDigits">CB_numberOfDecimalDigits</a></li><li><a href="global.html#CB_numberOfDecimals">CB_numberOfDecimals</a></li><li><a href="global.html#CB_numberOfIntegerDigits">CB_numberOfIntegerDigits</a></li><li><a href="global.html#CB_parseJSON">CB_parseJSON</a></li><li><a href="global.html#CB_parseString">CB_parseString</a></li><li><a href="global.html#CB_regularExpressionString">CB_regularExpressionString</a></li><li><a href="global.html#CB_renderString">CB_renderString</a></li><li><a href="global.html#CB_replaceAll">CB_replaceAll</a></li><li><a href="global.html#CB_rtrim">CB_rtrim</a></li><li><a href="global.html#CB_scriptPath">CB_scriptPath</a></li><li><a href="global.html#CB_scriptPathCalculate">CB_scriptPathCalculate</a></li><li><a href="global.html#CB_setCookie">CB_setCookie</a></li><li><a href="global.html#CB_setDatum">CB_setDatum</a></li><li><a href="global.html#CB_sizeOf">CB_sizeOf</a></li><li><a href="global.html#CB_sizeof">CB_sizeof</a></li><li><a href="global.html#CB_stringifyJSON">CB_stringifyJSON</a></li><li><a href="global.html#CB_symmetricCall">CB_symmetricCall</a></li><li><a href="global.html#CB_symmetricCallClear">CB_symmetricCallClear</a></li><li><a href="global.html#CB_this">CB_this</a></li><li><a href="global.html#CB_trim">CB_trim</a></li>
</ul>
</li>
</ul>
<div class="col-sm-3 col-md-3">
<form class="navbar-form" role="search">
<div class="input-group">
<input type="text" class="form-control" placeholder="Search" name="q" id="search-input">
<div class="input-group-btn">
<button class="btn btn-default" id="search-submit"><i class="glyphicon glyphicon-search"></i></button>
</div>
</div>
</form>
</div>
</div>
</div>
</div>
<div class="container" id="toc-content" style="width:100%;">
<div class="row" style="width:100%;">
<div class="col-md-12">
<div id="main">
<h1 class="page-title">Source: CrossBase/device/CB_Device.js</h1>
<section>
<article>
<pre
class="sunlight-highlight-javascript linenums">/**
* @file Device management. Contains the {@link CB_Device} static class.
* @author Joan Alba Maldonado <workindalian@gmail.com>
* @license Creative Commons Attribution 4.0 International. See more at {@link https://crossbrowdy.com/about#what_is_the_crossbrowdy_copyright_and_license}.
*/
/**
* Static class to manage the device. It will return itself if it is tried to be instantiated.
* @namespace
* @todo Think about defining a parameter on many of the events to disable automatic normalization of the event object.
*/
var CB_Device = function() { return CB_Device; };
{
CB_Device.initialized = false; //It will tells whether the object has been initialized or not.
//Initializes all values:
CB_Device.init = function()
{
if (CB_Device.initialized) { return CB_Device; }
//The object has been initialized:
CB_Device.initialized = true;
//If now() static function not available, uses getTime() method:
if (!Date.now) { Date.now = function() { return new Date().getTime(); }; }
//If desired and it is possible, changes the CB_Device.getTime method to use high precission:
if (CB_Configuration.CrossBase.CB_Device_getTime_HIGH_PRECISION && window.performance && window.performance.timing && window.performance.timing.navigationStart) //window.performance.now is always available (polyfilled).
{
CB_Device.getTime = function() { return window.performance.timing.navigationStart + window.performance.now() || Date.now(); };
}
//Initializes sub-classes:
CB_Device.Battery.init();
return CB_Device;
}
/**
* Gets a timestamp in milliseconds (elapsed since 1st of January 1970 00:00:00 UTC) representing the current time. Using high precision if the {@link CB_Configuration.CrossBase.CB_Device_getTime_HIGH_PRECISION} option is true (it would return '[window.performance.timing.navigationStart]{@link https://developer.mozilla.org/en-US/docs/Web/API/PerformanceTiming/navigationStart} + [window.performance.now]{@link https://developer.mozilla.org/en-US/docs/Web/API/Performance/now}()', where '[window.performance.now]{@link https://developer.mozilla.org/en-US/docs/Web/API/Performance/now}' could be polyfilled) or normal precision otherwise (it would return '[Date.now]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now}()', where '[Date.now]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now}' could be polyfilled).
* @function
* @returns {integer} Returns a timestamp in milliseconds (elapsed since 1st of January 1970 00:00:00 UTC) representing the current time or zero (0) if it was not possible.
*/
CB_Device.getTime = function() //Can be replaced in CB_Device.init to use high precision.
{
return Date.now();
};
/**
* Gets the time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin}. If possible, it uses [window.performance.now]{@link https://developer.mozilla.org/en-US/docs/Web/API/Performance/now}, which could be polyfilled (if it is polyfilled it will not have high precision timing but, if it is not, time precision/resolution will depend on the client).
* @function
* @returns {number} Returns the time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin}. If possible, it uses [window.performance.now]{@link https://developer.mozilla.org/en-US/docs/Web/API/Performance/now}, which could be polyfilled (if it is polyfilled it will not have high precision timing but, if it is not, time precision/resolution will depend on the client).
*/
CB_Device.getTiming = function() //Can be replaced in CB_Device.init to use high precision.
{
return window.performance.now();
};
//Sets a function to execute when a desired event is fired:
CB_Device._setEvent = function(eventName, eventFunction, keepOldFunction, useCapture, target)
{
//If they are not set, use default values for optional parameters:
if (typeof(keepOldFunction) === "undefined" || keepOldFunction === null) { keepOldFunction = true; } //If not set, it keeps old function by default.
if (typeof(target) === "undefined" || target === null)
{
target = window;
}
//If a function has been sent:
if (typeof(eventFunction) === "function")
{
//If able, adds the function given to the event:
CB_Events.add(target, eventName, eventFunction, useCapture, keepOldFunction, true);
}
//...but if the function given is null, it will cancel the event:
else if (eventFunction === null)
{
CB_Events.removeByName(target, eventName);
}
}
} //End of the static class CB_Device.
/**
* Static class to manage the device's location. It will return itself if it is tried to be instantiated.
* @namespace
* @todo Normalize more differences between web clients.
*/
CB_Device.Location = function() { return CB_Device.Location; };
{
/**
* Keeps the last watch ID that gets the location constantly. Used by the {@link CB_Device.Location.getConstantly} function.
* @var
* @readonly
* @type {integer|null}
* @default
*/
CB_Device.Location.getConstantly_lastId = null;
/**
* Keeps the "WakeLock" ([MozWakeLock]{@link https://developer.mozilla.org/docs/Web/API/MozWakeLock}) object to be able to release the lock related with the GPS (so far, only works in Firefox/Firefox OS). Used by the {@link CB_Device.Location.keepAwake} function.
* @var
* @readonly
* @type {Object|null}
* @default
*/
CB_Device.Location.keepAwake_locationLockGPS = null;
/**
* Keeps the callback function used when location can be gotten successfully for the {@link CB_Device.Location.get} function.
* @var
* @readonly
* @type {function|null}
* @default
*/
CB_Device.Location.get_callbackOk = null;
/**
* Keeps the callback function used when there is an error getting the location for the {@link CB_Device.Location.get} function.
* @var
* @readonly
* @type {function|null}
* @default
*/
CB_Device.Location.get_callbackError = null;
/**
* Keeps the last options used by the {@link CB_Device.Location.get} function.
* @var
* @readonly
* @type {Object|undefined}
* @default
*/
CB_Device.Location.get_options = undefined;
/**
* Keeps the callback function used when location can be gotten successfully for the {@link CB_Device.Location.getConstantly} function.
* @var
* @readonly
* @type {function|null}
* @default
*/
CB_Device.Location.getConstantly_callbackOk = null;
/**
* Keeps the callback function used when there is an error getting the location for the {@link CB_Device.Location.getConstantly} function.
* @var
* @readonly
* @type {function|null}
* @default
*/
CB_Device.Location.getConstantly_callbackError = null;
/**
* Keeps the last options used by the {@link CB_Device.Location.getConstantly} function.
* @var
* @readonly
* @type {Object|undefined}
* @default
*/
CB_Device.Location.getConstantly_options = undefined;
/**
* Tells whether the [Geolocation API]{@link https://developer.mozilla.org/docs/Web/API/Geolocation} (or compatible one as [Apache Cordova's Geolocation plugin]{@link https://github.com/apache/cordova-plugin-geolocation}) is supported or not.
* @function
* @returns {boolean}
*/
CB_Device.Location.isSupported = function()
{
return (window.navigator && "geolocation" in navigator && typeof(navigator.geolocation.getCurrentPosition) !== "undefined");
}
CB_Device.Location._getFirstTime = false;
/**
* Gets the current position. Uses the [Geolocation API]{@link https://developer.mozilla.org/docs/Web/API/Geolocation} (or compatible one as [Apache Cordova's Geolocation plugin]{@link https://github.com/apache/cordova-plugin-geolocation}).
* @function
* @param {function} [callbackOk] - Callback that will be called if it gets the location successfully. Following the same rules as the first parameter of the native [getCurrentPosition]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/getCurrentPosition} function.
* @param {function} [callbackError] - Callback that will be called if there is any error getting the location. Following the same rules as the second parameter of the native [getCurrentPosition]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/getCurrentPosition} function.
* @param {Object} [options] - Object that represents the desired options. This parameter will be ignored if "keepOldOptions" is set to true. Following the same rules as the third parameter of the native [getCurrentPosition]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/getCurrentPosition} function.
* @param {boolean} [keepOldCallbackOk=true] - If it is set to false, it will not keep the old previous "callbackOk" (if any) which was/were set in previous calls to this function.
* @param {boolean} [keepOldCallbackError=true] - If it is set to false, it will not keep the old previous "callbackError" (if any) which was/were set in previous calls to this function.
* @param {boolean} [keepOldOptions=false] - If it is set to true, it will ignore the given options and it will try to use the old previous options (if any) which were set in previous calls to this function.
* @returns {undefined|false} Returns false in the case that [Geolocation API]{@link https://developer.mozilla.org/docs/Web/API/Geolocation} (or compatible one as [Apache Cordova's Geolocation plugin]{@link https://github.com/apache/cordova-plugin-geolocation}) is not supported or undefined otherwise.
*/
CB_Device.Location.get = function(callbackOk, callbackError, options, keepOldCallbackOk, keepOldCallbackError, keepOldOptions)
{
if (typeof(keepOldCallbackOk) === "undefined" || keepOldCallbackOk === null) { keepOldCallbackOk = true; } //If not set, it keeps old ok function by default.
if (typeof(keepOldCallbackError) === "undefined" || keepOldCallbackError === null) { keepOldCallbackError = true; } //If not set, it keeps old error function by default.
if (CB_Device.Location.isSupported() && typeof(callbackOk) === "function")
{
if (!keepOldCallbackOk)
{
CB_Device.Location.get_callbackOk = callbackOk;
}
else
{
var callbackOkOld = CB_Device.Location.get_callbackOk;
CB_Device.Location.get_callbackOk =
function(locationObject)
{
if (typeof(callbackOkOld) === "function") { callbackOkOld(locationObject); }
if (typeof(callbackOk) === "function") { callbackOk(locationObject); }
};
}
if (!keepOldCallbackError)
{
CB_Device.Location.get_callbackError = callbackError;
}
else
{
var callbackErrorOld = CB_Device.Location.get_callbackError;
CB_Device.Location.get_callbackError =
function(error)
{
if (typeof(callbackErrorOld) === "function") { callbackErrorOld(error); }
if (typeof(callbackError) === "function") { callbackError(error); }
};
}
if (!keepOldOptions) { CB_Device.Location.get_options = options; }
if (CB_Device.Location._getFirstTime === true)
{
CB_Device.Location._getFirstTime = false;
navigator.geolocation.getCurrentPosition(function(){}, function(){}, {}); //Hack. Source: Niels Steenbeek @ http://stackoverflow.com/questions/3397585/navigator-geolocation-getcurrentposition-sometimes-works-sometimes-doesnt
}
return navigator.geolocation.getCurrentPosition(CB_Device.Location.get_callbackOk, CB_Device.Location.get_callbackError, CB_Device.Location.get_options);
}
return false;
}
CB_Device.Location._getConstantlyFirstTime = true;
/**
* Starts or stops getting the current position constantly (real-time) every time it changes. Uses the [Geolocation API]{@link https://developer.mozilla.org/docs/Web/API/Geolocation} (or compatible one as [Apache Cordova's Geolocation plugin]{@link https://github.com/apache/cordova-plugin-geolocation}).
* @function
* @param {function|integer} [callbackOkOrId={@link CB_Device.Location.getConstantly_lastId}] - In the case that we want to start getting the position, use a function callback that will be called every time it gets the location successfully (using the native [watchPosition]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/watchPosition} function). To stop getting the position, use the watch ID that we want to stop (using the native [clearWatch]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/clearWatch} function). Following the same rules as the first parameter of the native [watchPosition]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/watchPosition} function (when we want to start watching) or the first parameter of [clearWatch]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/clearWatch} function (when we want to stop watching).
* @param {function} [callbackError] - Callback that will be called if there is any error getting the location. Only used when we want to start getting the current position ("callbackOkOrId" is a function). Following the same rules as the second parameter of the native [watchPosition]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/watchPosition} function.
* @param {Object} [options] - Object that represents the desired options. This parameter will be ignored if "keepOldOptions" is set to true. Only used when we want to start getting the current position ("callbackOkOrId" is a function). Following the same rules as the third parameter of the native [watchPosition]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/watchPosition} function.
* @param {boolean} [keepOldCallbackOk=true] - If it is set to false, it will not keep the old previous "callbackOk" (if any) which was/were set in previous calls to this function. Only used when we want to start getting the current position ("callbackOkOrId" is a function).
* @param {boolean} [keepOldCallbackError=true] - If it is set to false, it will not keep the old previous "callbackError" (if any) which was/were set in previous calls to this function. Only used when we want to start getting the current position ("callbackOkOrId" is a function).
* @param {boolean} [keepOldOptions=false] - If it is set to true, it will ignore the given options and it will try to use the old previous options (if any) which were set in previous calls to this function. Only used when we want to start getting the current position ("callbackOkOrId" is a function).
* @returns {integer|undefined|false} Returns false in the case that [Geolocation API]{@link https://developer.mozilla.org/docs/Web/API/Geolocation} (or compatible one as [Apache Cordova's Geolocation plugin]{@link https://github.com/apache/cordova-plugin-geolocation}) is not supported. In the case that we want to start getting the current position ("callbackOkOrId" is a function), it will return the watch ID that has been created. In the case that we want to stop getting the position ("callbackOkOrId" is a watch ID), it will return undefined.
*/
CB_Device.Location.getConstantly = function(callbackOkOrId, callbackError, options, keepOldCallbackOk, keepOldCallbackError, keepOldOptions)
{
//If either callback function has been given, starts getting the position constantly:
if (typeof(callbackOkOrId) === "function")
{
if (typeof(keepOldCallbackOk) === "undefined" || keepOldCallbackOk === null) { keepOldCallbackOk = true; } //If not set, it keeps old ok function by default.
if (typeof(keepOldCallbackError) === "undefined" || keepOldCallbackError === null) { keepOldCallbackError = true; } //If not set, it keeps old error function by default.
if (CB_Device.Location.isSupported() && typeof(navigator.geolocation.watchPosition) !== "undefined")
{
if (!keepOldCallbackOk)
{
CB_Device.Location.getConstantly_callbackOk = callbackOkOrId;
}
else
{
var callbackOkOld = CB_Device.Location.getConstantly_callbackOk;
CB_Device.Location.getConstantly_callbackOk =
function(locationObject)
{
if (typeof(callbackOkOld) === "function") { callbackOkOld(locationObject); }
if (typeof(callbackOkOrId) === "function") { callbackOkOrId(locationObject); }
};
}
if (!keepOldCallbackError)
{
CB_Device.Location.getConstantly_callbackError = callbackError;
}
else
{
var callbackErrorOld = CB_Device.Location.getConstantly_callbackError;
CB_Device.Location.getConstantly_callbackError =
function(error)
{
if (typeof(callbackErrorOld) === "function") { callbackErrorOld(error); }
if (typeof(callbackError) === "function") { callbackError(error); }
};
}
if (!keepOldOptions) { CB_Device.Location.getConstantly_options = options; }
if (CB_Device.Location._getConstantlyFirstTime === true)
{
CB_Device.Location._getConstantlyFirstTime = false;
navigator.geolocation.watchPosition(function(){}, function(){}, {}); //Hack. Source: Niels Steenbeek @ http://stackoverflow.com/questions/3397585/navigator-geolocation-getcurrentposition-sometimes-works-sometimes-doesnt
}
CB_Device.Location.getConstantly_lastId = navigator.geolocation.watchPosition(CB_Device.Location.getConstantly_callbackOk, CB_Device.Location.getConstantly_callbackError, CB_Device.Location.getConstantly_options);
return CB_Device.Location.getConstantly_lastId;
}
}
//...otherwise, stops getting the position constantly:
else
{
if (window.navigator && "geolocation" in navigator && typeof(navigator.geolocation.clearWatch) !== "undefined")
{
//if (typeof(callbackOkOrId) === "undefined" || callbackOkOrId === null) { callbackOkOrId = CB_Device.Location.getConstantly_lastId; }
if (isNaN(callbackOkOrId) || CB_trim(callbackOkOrId) === "") { callbackOkOrId = CB_Device.Location.getConstantly_lastId; }
return navigator.geolocation.clearWatch(callbackOkOrId);
}
}
return false;
}
/**
* Stops getting the current position constantly (real-time) every time it changes. Uses the [Geolocation API]{@link https://developer.mozilla.org/docs/Web/API/Geolocation} (or compatible one as [Apache Cordova's Geolocation plugin]{@link https://github.com/apache/cordova-plugin-geolocation}).
* @function
* @param {integer} [id={@link CB_Device.Location.getConstantly_lastId}] - The watch ID that we want to stop. Following the same rules as the first parameter of the native [clearWatch]{@link https://developer.mozilla.org/docs/Web/API/Geolocation/clearWatch} function.
* @param {boolean} [keepOldCallbackOk=false] - If it is set to false, it will not remove the current "callbackOk" (if any) which was/were set previously.
* @param {boolean} [keepOldCallbackError=false] - If it is set to false, it will remove the current "callbackError" (if any) which was/were set previously.
* @param {boolean} [keepOldOptions=false] - If it is set to false, it will remove the current "options" (if any) which were set previously.
* @returns {undefined|false} Returns false in the case that [Geolocation API]{@link https://developer.mozilla.org/docs/Web/API/Geolocation} (or compatible one as [Apache Cordova's Geolocation plugin]{@link https://github.com/apache/cordova-plugin-geolocation}) is not supported or undefined otherwise.
*/
CB_Device.Location.getConstantlyDisable = function(id, keepOldCallbackOk, keepOldCallbackError, keepOldOptions)
{
//if (typeof(id) === "function") { id = undefined; } //Prevents calling CB_Device.Location.getConstantly with a function as parameter since that is for starting the watcher.
if (isNaN(id) || !id) { id = undefined; } //Prevents calling CB_Device.Location.getConstantly with a function as parameter since that is for starting the watcher.
if (!keepOldCallbackOk) { CB_Device.Location.getConstantly_callbackOk = null; }
if (!keepOldCallbackError) { CB_Device.Location.getConstantly_callbackError = null; }
if (!keepOldOptions) { CB_Device.Location.getConstantly_options = undefined; }
return CB_Device.Location.getConstantly(id);
}
/**
* Keeps or stops keeping the application getting the position, even when the application is invisible or screen is locked, by using [requestWakeLock]{@link https://developer.mozilla.org/docs/Web/API/Navigator/requestWakeLock} (so far, only works in Firefox/Firefox OS).
* @function
* @param {boolean} [keepAwake=true] - Defines whether we want to keep it awake or stop doing it.
* @param {Object} [lock={@link CB_Device.Location.keepAwake_locationLockGPS}] - The "WakeLock" ([MozWakeLock]{@link https://developer.mozilla.org/docs/Web/API/MozWakeLock}) object that we want to unlock. It will be used only when "keepAwake" is set to false.
* @returns {undefined|Object|false} Returns false in the case that "WakeLock" ([MozWakeLock]{@link https://developer.mozilla.org/docs/Web/API/MozWakeLock}) is not supported or something went wrong. Returns the "WakeLock" ([MozWakeLock]{@link https://developer.mozilla.org/docs/Web/API/MozWakeLock}) object in the case that we wanted to keep it awake ("keepAwake" is set to true). Returns undefined in the case that we do not want it to keep it awake ("keepAwake" is set to false and the lock is a valid "WakeLock" object).
*/
CB_Device.Location.keepAwake = function(keepAwake, lock)
{
if (typeof(keepAwake) === "undefined" || keepAwake === null) { keepAwake = true; }
//If we want to lock the device to keep it awake:
if (keepAwake)
{
if (window.navigator && typeof(window.navigator.requestWakeLock) !== "undefined")
{
CB_Device.Location.keepAwake_locationLockGPS = window.navigator.requestWakeLock("gps"); //So far, only works in Firefox/Firefox OS.
return CB_Device.Location.keepAwake_locationLockGPS;
}
}
//...otherwise, if we want to release the lock that keeps the device awake:
else
{
if (typeof(lock) === "undefined" || lock === null)
{
if (typeof(CB_Device.Location.keepAwake_locationLockGPS) !== "undefined" && CB_Device.Location.keepAwake_locationLockGPS !== null) { lock = CB_Device.Location.keepAwake_locationLockGPS; }
else { return false; }
}
if (typeof(lock.unlock) !== "undefined") { return lock.unlock(); } //So far, only works in Firefox/Firefox OS.
}
return false;
}
} //End of the static class CB_Device.Location.
/**
* Static class to manage the device's orientation. It will return itself if it is tried to be instantiated.
* @namespace
* @todo Normalize more differences between web clients.
*/
CB_Device.Orientation = function() { return CB_Device.Orientation; };
{
/**
* Keeps the last watch ID that gets the compass heading constantly using the [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation}. Used by the {@link CB_Device.Orientation.cordova_getCompassConstantly} function.
* @var
* @readonly
* @type {integer|null}
* @default
*/
CB_Device.Orientation.cordova_getCompassConstantly_lastId = null;
/**
* Tells whether the [Device Orientation Event]{@link https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent} (used by the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} or compatible one) is supported or not.
* @function
* @returns {boolean}
* @todo Think about using the "ondeviceorientationabsolute" event.
*/
CB_Device.Orientation.isSupported = function()
{
return ("DeviceOrientationEvent" in window || "ondeviceorientation" in window);
}
/**
* Tells whether the [MozOrientation API]{@link https://developer.mozilla.org/docs/Web/Events/MozOrientation} is supported or not.
* @function
* @returns {boolean}
*/
CB_Device.Orientation.isMozOrientationSupported = function()
{
return ("MozOrientation" in window);
}
/**
* Sets a function to execute for the [Device Orientation Event]{@link https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent} (used by the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} or compatible one) or removes it. Falls back to the [MozOrientation API]{@link https://developer.mozilla.org/docs/Web/Events/MozOrientation} if possible.
* @function
* @param {function|null} eventFunction - The function that will be called when the event is fired. The event object received will already be normalized by the {@link CB_Device.Orientation.normalizeEvent} function automatically. Following the same rules as in {@link https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent}. If a null value is used, the event will be removed.
* @param {boolean} [keepOldFunction=true] - Defines whether we want to keep any possible previous event listener or not.
* @param {float} [useCapture=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]{@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener} method and will be used as its third parameter.
* @returns {undefined|false} Returns false in the case that neither the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} (or compatible one) nor the [MozOrientation API]{@link https://developer.mozilla.org/docs/Web/Events/MozOrientation} are supported or undefined otherwise.
* @todo Think about using the "deviceorientationabsolute" event.
*/
CB_Device.Orientation.onChange = function(eventFunction, keepOldFunction, useCapture)
{
if (CB_Device.Orientation.isSupported())
{
return CB_Device.Orientation._setEvent("deviceorientation", eventFunction, keepOldFunction, useCapture, window);
}
else if (CB_Device.Orientation.isMozOrientationSupported())
{
return CB_Device.Orientation._setEvent("MozOrientation", eventFunction, keepOldFunction, useCapture, window);
}
else { return false; }
}
//Sets a function to execute when a desired event is fired:
CB_Device.Orientation._setEvent = function(eventName, eventFunction, keepOldFunction, useCapture, target)
{
var wrapperFunction = eventFunction;
if (typeof(eventFunction) === "function")
{
wrapperFunction = function(e)
{
e = CB_Device.Orientation.normalizeEvent(e, eventName);
return eventFunction(e);
};
}
CB_Device._setEvent(eventName, wrapperFunction, keepOldFunction, useCapture, target);
}
/**
* Normalizes the data gotten from the [Device Orientation Event]{@link https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent} produced by different clients to try to match the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} and follow always the same rules as much as possible.
* @function
* @param {Event} e - The event object that we want to normalize.
* @param {('deviceorientation'|'MozOrientation')} eventName - The name of the event that we want to normalize. Case sensitive.
* @returns {Event} Returns the given event object again but normalized (if possible).
* @todo Think about using the "deviceorientationabsolute" event.
* @todo Normalize more differences between web clients.
*/
CB_Device.Orientation.normalizeEvent = function(e, eventName)
{
e = CB_Events.normalize(e);
if (typeof(e) !== "undefined" && e !== null)
{
if (eventName === "deviceorientation")
{
if (e.webkitCompassHeading) { e.alpha = /*360 - */e.webkitCompassHeading; } //Source: https://mobiforge.com/design-development/html5-mobile-web-device-orientation-events and https://dev.opera.com/articles/w3c-device-orientation-usage/
}
else if (eventName === "MozOrientation")
{
if (!e.gamma && !e.beta) //For FF3.6+ (Source: https://developer.mozilla.org/en-US/docs/Web/Events/MozOrientation)
{
e.gamma = -(e.x * (180 / Math.PI));
e.beta = -(e.y * (180 / Math.PI));
}
}
//TODO: there are still more differences between web clients!
}
return e;
}
/**
* Tells whether the [Compass Needs Calibration Event]{@link https://w3c.github.io/deviceorientation/spec-source-orientation.html#compassneedscalibration} (used by the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} or compatible one) is supported or not.
* @function
* @returns {boolean}
*/
CB_Device.Orientation.isCompassNeedsCalibrationSupported = function()
{
return ("CompassNeedsCalibration" in window || "oncompassneedscalibration" in window); //return ("DeviceMotionEvent" in window || "ondevicemotion" in window);
}
/**
* Sets a function to execute for the [Compass Needs Calibration Event]{@link https://w3c.github.io/deviceorientation/spec-source-orientation.html#compassneedscalibration} (used by the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} or compatible one) or removes it.
* @function
* @param {function|null} eventFunction - The function that will be called when the event is fired. Following the same rules as in {@link https://w3c.github.io/deviceorientation/spec-source-orientation.html#compassneedscalibration}. If a null value is used, the event will be removed.
* @param {boolean} [keepOldFunction=true] - Defines whether we want to keep any possible previous event listener or not.
* @param {float} [useCapture=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]{@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener} method and will be used as its third parameter.
* @returns {undefined|false} Returns false in the case that the [Compass Needs Calibration Event]{@link https://w3c.github.io/deviceorientation/spec-source-orientation.html#compassneedscalibration} is not supported or undefined otherwise.
*/
CB_Device.Orientation.onCompassNeedsCalibration = function(eventFunction, keepOldFunction, useCapture)
{
if (!CB_Device.Orientation.isCompassNeedsCalibrationSupported()) { return false; }
return CB_Device._setEvent("compassneedscalibration", eventFunction, keepOldFunction, useCapture, window);
}
/**
* Tells whether the [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation} is available or not.
* @function
* @returns {boolean}
*/
CB_Device.Orientation.cordova_isCompassSupported = function()
{
return (typeof(navigator) !== "undefined" && navigator !== null && navigator.compass && navigator.compass.getCurrentHeading && navigator.compass.watchHeading && navigator.compass.clearWatch);
}
/**
* Gets the compass heading using the [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation}. Uses "navigator.compass.getCurrentHeading" internally.
* @function
* @param {function} callbackOk - The function that will be called when it succeeds getting the compass heading. Following the same rules as in {@link https://github.com/apache/cordova-plugin-device-orientation} ("navigator.compass.getCurrentHeading" function).
* @param {function} callbackError - The function that will be called if there is any error getting the compass heading. Following the same rules as in {@link https://github.com/apache/cordova-plugin-device-orientation} ("navigator.compass.getCurrentHeading" function).
* @returns {undefined|false} Returns false in the case that the [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation} is not supported or undefined otherwise.
* @todo Add a function to normalize the event and call it automatically.
*/
CB_Device.Orientation.cordova_getCompass = function(callbackOk, callbackError)
{
if (!CB_Device.Orientation.cordova_isCompassSupported()) { return false; }
navigator.compass.getCurrentHeading(callbackOk, callbackError);
}
/**
* Starts or stops getting the compass heading constantly at a regular interval. Uses the [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation} ("navigator.compass.watchHeading" and "navigator.compass.clearWatch" functions).
* @function
* @param {function|integer} [callbackOkOrId={@link 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 {@link https://github.com/apache/cordova-plugin-device-orientation}.
* @param {function} [callbackError] - 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 {@link https://github.com/apache/cordova-plugin-device-orientation}.
* @param {Object} [options] - 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 {@link https://github.com/apache/cordova-plugin-device-orientation}.
* @returns {integer|undefined|false} Returns false in the case that [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation} 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.
* @todo Add a function to normalize the event and call it automatically.
* @todo Add parameters to keep old callbacks and options.
*/
CB_Device.Orientation.cordova_getCompassConstantly = function(callbackOkOrId, callbackError, options) //Note: options can be an object with two optional properties ("frequency" and "filter").
{
if (!CB_Device.Orientation.cordova_isCompassSupported()) { return false; }
//If either callback function has been given, starts getting the compass heading constantly:
if (typeof(callbackOkOrId) === "function")
{
CB_Device.Orientation.cordova_getCompassConstantly_lastId = navigator.compass.watchHeading(callbackOkOrId, callbackError, options);
return CB_Device.Orientation.cordova_getCompassConstantly_lastId;
}
//...otherwise, stops getting the compass heading constantly:
else
{
//if (typeof(callbackOkOrId) === "undefined" || callbackOkOrId === null) { callbackOkOrId = CB_Device.Orientation.cordova_getCompassConstantly_lastId; }
if (isNaN(callbackOkOrId) || CB_trim(callbackOkOrId) === "") { callbackOkOrId = CB_Device.Orientation.cordova_getCompassConstantly_lastId; }
navigator.compass.clearWatch(callbackOkOrId);
return;
}
return false;
}
/**
* Stops getting the compass heading constantly at a regular interval. Uses the [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation} ("navigator.compass.clearWatch" function).
* @function
* @param {integer} [id={@link 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 {@link https://github.com/apache/cordova-plugin-device-orientation}.
* @returns {undefined|false} Returns false in the case that [Apache Cordova's Device Orientation plugin]{@link https://github.com/apache/cordova-plugin-device-orientation} is not supported or undefined otherwise.
* @todo Add parameters to keep old callbacks and options.
*/
CB_Device.Orientation.cordova_getCompassConstantlyDisable = function(id)
{
if (typeof(id) === "function") { id = undefined; } //Prevents calling CB_Device.Orientation.cordova_getCompassConstantly with a function as parameter since that is for starting the watcher.
return CB_Device.Orientation.cordova_getCompassConstantly(id);
}
} //End of the static class CB_Device.Orientation.
/**
* Static class to manage the device's motion. It will return itself if it is tried to be instantiated.
* @namespace
* @todo Normalize more differences between web clients.
*/
CB_Device.Motion = function() { return CB_Device.Motion; };
{
/**
* Keeps the last watch ID that gets the acceleration constantly using the [Apache Cordova's Device Motion plugin]{@link https://github.com/apache/cordova-plugin-device-motion}. Used by the {@link CB_Device.Motion.cordova_getAccelerationConstantly} function.
* @var
* @readonly
* @type {integer|null}
* @default
*/
CB_Device.Motion.cordova_getAccelerationConstantly_lastId = null;
/**
* Tells whether the [Device Motion Event]{@link https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent} (used by the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} or compatible one) is supported or not.
* @function
* @returns {boolean}
*/
CB_Device.Motion.isSupported = function()
{
return ("DeviceMotionEvent" in window || "ondevicemotion" in window);
}
/**
* Sets a function to execute for the [Device Motion Event]{@link https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent} (used by the [Device Orientation API]{@link https://developer.mozilla.org/docs/Web/API/Detecting_device_orientation} or compatible one) or removes it.
* @function
* @param {function|null} eventFunction - The function that will be called when the event is fired. Following the same rules as in {@link https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent}. If a null value is used, the event will be removed.
* @param {boolean} [keepOldFunction=true] - Defines whether we want to keep any possible previous event listener or not.
* @param {float} [useCapture=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]{@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener} method and will be used as its third parameter.
* @returns {undefined|false} Returns false in the case that the [Device Motion Event]{@link https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent} is not supported or undefined otherwise.
*/
CB_Device.Mot