diff --git a/js/ui/cordova/plugins/cordova-plugin-android-sensor-listeners/README.md b/js/ui/cordova/plugins/cordova-plugin-android-sensor-listeners/README.md new file mode 100644 index 0000000..1e06453 --- /dev/null +++ b/js/ui/cordova/plugins/cordova-plugin-android-sensor-listeners/README.md @@ -0,0 +1,100 @@ +# Cordova Android Sensor Listeners Plugin + +This plugin gives easy access to every available [Android's sensors](https://developer.android.com/guide/topics/sensors/sensors_overview.html). + +## Install + +```sh +cordova plugin add https://github.com/QuentinRoy/cordova-plugin-android-sensor-listeners.git +``` + + + +## API: sensors + +* [sensors](#sensors) : object + * [.addSensorListener(sensorType, samplingPeriod, listener, [callback])](#sensors.addSensorListener) ⇒ undefined + * [.removeSensorListener(sensorType, samplingPeriod, listener, [callback])](#sensors.removeSensorListener) ⇒ undefined + + + +### sensors.addSensorListener(sensorType, samplingPeriod, listener, [callback]) ⇒ undefined +Add a sensor listener. + +**Kind**: static method of [sensors](#sensors) + +| Param | Type | Description | +| --- | --- | --- | +| sensorType | string | The sensor type's constant name (as defined by [Android's Sensor](https://developer.android.com/guide/topics/sensors/sensors_overview.html), but without the prefix `"TYPE_"`). | +| samplingPeriod | string | The sampling period's constant name (as accepted by [SensorManager#registerListener](https://developer.android.com/reference/android/hardware/SensorManager.html#registerListener(android.hardware.SensorEventListener,%20android.hardware.Sensor,%20int)), but without the prefix `"SENSOR_DELAY_"`). | +| listener | [sensorEventListener](#sensorEventListener) | The listener to register. | +| [callback] | [errorFirstCallback](#errorFirstCallback) | A node-style callback to be called upon success or failure of the operation. | + +**Example** +```js +function listener(event) { + console.log("device's rotation is " + event.values.join(",")); +} + +sensors.addSensorListener("ROTATION_VECTOR", "GAME", listener, function(error) { + if (error) console.error("Could not listen to sensor"); +}); +``` + + +### sensors.removeSensorListener(sensorType, samplingPeriod, listener, [callback]) ⇒ undefined +Remove a sensor listener. + +**Kind**: static method of [sensors](#sensors) + +| Param | Type | Description | +| --- | --- | --- | +| sensorType | string | The type of the sensor as registered when the listener was added (see [addSensorListener](#sensors.addSensorListener)). | +| samplingPeriod | string | The sampling period as registered when the listener was added (see [addSensorListener](#sensors.addSensorListener)). | +| listener | [sensorEventListener](#sensorEventListener) | The listener to remove. | +| [callback] | [errorFirstCallback](#errorFirstCallback) | A node-style callback to be called upon success or failure of the operation. | + +**Example** +```js +sensors.removeSensorListener("ROTATION_VECTOR", "GAME", listener, function(error) { + if (error) console.error("Could not stop listening to sensor"); +}); +``` + + +## SensorEvent : Object +Event emitted from sensors. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| sensor | string | The type of sensor that is listened to. | +| sampling | string | The sampling period the sensor is listened to by the receiving event listener. | +| timeStamp | int | The time the event was emitted. | +| values | Array.<float> | The sensor values. | + + + +## errorFirstCallback : function +This callback is used to get responses from async calls. It complies with +nodeJS callback style. + +**Kind**: global typedef + +| Param | Type | Description | +| --- | --- | --- | +| [err] | \* | the error or undefined if everything went fine | +| data | \* | the response or the called function | + + + +## sensorEventListener : function +This listener is used to receive events from sensors. + +**Kind**: global typedef + +| Param | Type | Description | +| --- | --- | --- | +| evt | [SensorEvent](#SensorEvent) | the event emitted by one of the sensor |