1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Touchgui/plugins/org.apache.cordova.vibration/doc/index.md Thu Jun 04 14:50:33 2015 +0200
1.3 @@ -0,0 +1,175 @@
1.4 +<!---
1.5 + Licensed to the Apache Software Foundation (ASF) under one
1.6 + or more contributor license agreements. See the NOTICE file
1.7 + distributed with this work for additional information
1.8 + regarding copyright ownership. The ASF licenses this file
1.9 + to you under the Apache License, Version 2.0 (the
1.10 + "License"); you may not use this file except in compliance
1.11 + with the License. You may obtain a copy of the License at
1.12 +
1.13 + http://www.apache.org/licenses/LICENSE-2.0
1.14 +
1.15 + Unless required by applicable law or agreed to in writing,
1.16 + software distributed under the License is distributed on an
1.17 + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1.18 + KIND, either express or implied. See the License for the
1.19 + specific language governing permissions and limitations
1.20 + under the License.
1.21 +-->
1.22 +
1.23 +# org.apache.cordova.vibration
1.24 +
1.25 +This plugin aligns with the W3C vibration specification http://www.w3.org/TR/vibration/
1.26 +
1.27 +This plugin provides a way to vibrate the device.
1.28 +
1.29 +This plugin defines global objects including `navigator.vibrate`.
1.30 +
1.31 +Although in the global scope, they are not available until after the `deviceready` event.
1.32 +
1.33 + document.addEventListener("deviceready", onDeviceReady, false);
1.34 + function onDeviceReady() {
1.35 + console.log(navigator.vibrate);
1.36 + }
1.37 +
1.38 +## Installation
1.39 +
1.40 + cordova plugin add org.apache.cordova.vibration
1.41 +
1.42 +## Supported Platforms
1.43 +
1.44 +navigator.vibrate,<br />
1.45 +navigator.notification.vibrate
1.46 +- Amazon Fire OS
1.47 +- Android
1.48 +- BlackBerry 10
1.49 +- Firefox OS
1.50 +- iOS
1.51 +- Windows Phone 7 and 8
1.52 +
1.53 +navigator.notification.vibrateWithPattern,<br />navigator.notification.cancelVibration
1.54 +- Android
1.55 +- Windows Phone 8
1.56 +
1.57 +## vibrate (recommended)
1.58 +
1.59 +This function has three different functionalities based on parameters passed to it.
1.60 +
1.61 +###Standard vibrate
1.62 +
1.63 +Vibrates the device for a given amount of time.
1.64 +
1.65 + navigator.vibrate(time)
1.66 +
1.67 +or
1.68 +
1.69 + navigator.vibrate([time])
1.70 +
1.71 +
1.72 +-__time__: Milliseconds to vibrate the device. _(Number)_
1.73 +
1.74 +####Example
1.75 +
1.76 + // Vibrate for 3 seconds
1.77 + navigator.vibrate(3000);
1.78 +
1.79 + // Vibrate for 3 seconds
1.80 + navigator.vibrate([3000]);
1.81 +
1.82 +####iOS Quirks
1.83 +
1.84 +- __time__: Ignores the specified time and vibrates for a pre-set amount of time.
1.85 +
1.86 + navigator.vibrate(3000); // 3000 is ignored
1.87 +
1.88 +####Windows and Blackberry Quirks
1.89 +
1.90 +- __time__: Max time is 5000ms (5s) and min time is 1ms
1.91 +
1.92 + navigator.vibrate(8000); // will be truncated to 5000
1.93 +
1.94 +###Vibrate with a pattern (Android and Windows only)
1.95 +Vibrates the device with a given pattern
1.96 +
1.97 + navigator.vibrate(pattern);
1.98 +
1.99 +- __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_
1.100 +
1.101 +####Example
1.102 +
1.103 + // Vibrate for 1 second
1.104 + // Wait for 1 second
1.105 + // Vibrate for 3 seconds
1.106 + // Wait for 1 second
1.107 + // Vibrate for 5 seconds
1.108 + navigator.vibrate([1000, 1000, 3000, 1000, 5000]);
1.109 +
1.110 +####Windows Phone 8 Quirks
1.111 +
1.112 +- vibrate(pattern) falls back on vibrate with default duration
1.113 +
1.114 +###Cancel vibration (not supported in iOS)
1.115 +
1.116 +Immediately cancels any currently running vibration.
1.117 +
1.118 + navigator.vibrate(0)
1.119 +
1.120 +or
1.121 +
1.122 + navigator.vibrate([])
1.123 +
1.124 +or
1.125 +
1.126 + navigator.vibrate([0])
1.127 +
1.128 +Passing in a parameter of 0, an empty array, or an array with one element of value 0 will cancel any vibrations.
1.129 +
1.130 +## *notification.vibrate (deprecated)
1.131 +
1.132 +Vibrates the device for a given amount of time.
1.133 +
1.134 + navigator.notification.vibrate(time)
1.135 +
1.136 +- __time__: Milliseconds to vibrate the device. _(Number)_
1.137 +
1.138 +### Example
1.139 +
1.140 + // Vibrate for 2.5 seconds
1.141 + navigator.notification.vibrate(2500);
1.142 +
1.143 +### iOS Quirks
1.144 +
1.145 +- __time__: Ignores the specified time and vibrates for a pre-set amount of time.
1.146 +
1.147 + navigator.notification.vibrate();
1.148 + navigator.notification.vibrate(2500); // 2500 is ignored
1.149 +
1.150 +## *notification.vibrateWithPattern (deprecated)
1.151 +
1.152 +Vibrates the device with a given pattern.
1.153 +
1.154 + navigator.notification.vibrateWithPattern(pattern, repeat)
1.155 +
1.156 +- __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_
1.157 +- __repeat__: Optional index into the pattern array at which to start repeating (will repeat until canceled), or -1 for no repetition (default). _(Number)_
1.158 +
1.159 +### Example
1.160 +
1.161 + // Immediately start vibrating
1.162 + // vibrate for 100ms,
1.163 + // wait for 100ms,
1.164 + // vibrate for 200ms,
1.165 + // wait for 100ms,
1.166 + // vibrate for 400ms,
1.167 + // wait for 100ms,
1.168 + // vibrate for 800ms,
1.169 + // (do not repeat)
1.170 + navigator.notification.vibrateWithPattern([0, 100, 100, 200, 100, 400, 100, 800]);
1.171 +
1.172 +## *notification.cancelVibration (deprecated)
1.173 +
1.174 +Immediately cancels any currently running vibration.
1.175 +
1.176 + navigator.notification.cancelVibration()
1.177 +
1.178 +*Note - due to alignment with w3c spec, the starred methods will be phased out
