comparison: Touchgui/plugins/org.apache.cordova.vibration/doc/index.md
Touchgui/plugins/org.apache.cordova.vibration/doc/index.md
- changeset 0
- e8ccd40d0ef6
equal
deleted
inserted
replaced
| -1:000000000000 | 0:1238413de0a4 |
|---|---|
| 1 <!--- | |
| 2 Licensed to the Apache Software Foundation (ASF) under one | |
| 3 or more contributor license agreements. See the NOTICE file | |
| 4 distributed with this work for additional information | |
| 5 regarding copyright ownership. The ASF licenses this file | |
| 6 to you under the Apache License, Version 2.0 (the | |
| 7 "License"); you may not use this file except in compliance | |
| 8 with the License. You may obtain a copy of the License at | |
| 9 | |
| 10 http://www.apache.org/licenses/LICENSE-2.0 | |
| 11 | |
| 12 Unless required by applicable law or agreed to in writing, | |
| 13 software distributed under the License is distributed on an | |
| 14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| 15 KIND, either express or implied. See the License for the | |
| 16 specific language governing permissions and limitations | |
| 17 under the License. | |
| 18 --> | |
| 19 | |
| 20 # org.apache.cordova.vibration | |
| 21 | |
| 22 This plugin aligns with the W3C vibration specification http://www.w3.org/TR/vibration/ | |
| 23 | |
| 24 This plugin provides a way to vibrate the device. | |
| 25 | |
| 26 This plugin defines global objects including `navigator.vibrate`. | |
| 27 | |
| 28 Although in the global scope, they are not available until after the `deviceready` event. | |
| 29 | |
| 30 document.addEventListener("deviceready", onDeviceReady, false); | |
| 31 function onDeviceReady() { | |
| 32 console.log(navigator.vibrate); | |
| 33 } | |
| 34 | |
| 35 ## Installation | |
| 36 | |
| 37 cordova plugin add org.apache.cordova.vibration | |
| 38 | |
| 39 ## Supported Platforms | |
| 40 | |
| 41 navigator.vibrate,<br /> | |
| 42 navigator.notification.vibrate | |
| 43 - Amazon Fire OS | |
| 44 - Android | |
| 45 - BlackBerry 10 | |
| 46 - Firefox OS | |
| 47 - iOS | |
| 48 - Windows Phone 7 and 8 | |
| 49 | |
| 50 navigator.notification.vibrateWithPattern,<br />navigator.notification.cancelVibration | |
| 51 - Android | |
| 52 - Windows Phone 8 | |
| 53 | |
| 54 ## vibrate (recommended) | |
| 55 | |
| 56 This function has three different functionalities based on parameters passed to it. | |
| 57 | |
| 58 ###Standard vibrate | |
| 59 | |
| 60 Vibrates the device for a given amount of time. | |
| 61 | |
| 62 navigator.vibrate(time) | |
| 63 | |
| 64 or | |
| 65 | |
| 66 navigator.vibrate([time]) | |
| 67 | |
| 68 | |
| 69 -__time__: Milliseconds to vibrate the device. _(Number)_ | |
| 70 | |
| 71 ####Example | |
| 72 | |
| 73 // Vibrate for 3 seconds | |
| 74 navigator.vibrate(3000); | |
| 75 | |
| 76 // Vibrate for 3 seconds | |
| 77 navigator.vibrate([3000]); | |
| 78 | |
| 79 ####iOS Quirks | |
| 80 | |
| 81 - __time__: Ignores the specified time and vibrates for a pre-set amount of time. | |
| 82 | |
| 83 navigator.vibrate(3000); // 3000 is ignored | |
| 84 | |
| 85 ####Windows and Blackberry Quirks | |
| 86 | |
| 87 - __time__: Max time is 5000ms (5s) and min time is 1ms | |
| 88 | |
| 89 navigator.vibrate(8000); // will be truncated to 5000 | |
| 90 | |
| 91 ###Vibrate with a pattern (Android and Windows only) | |
| 92 Vibrates the device with a given pattern | |
| 93 | |
| 94 navigator.vibrate(pattern); | |
| 95 | |
| 96 - __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_ | |
| 97 | |
| 98 ####Example | |
| 99 | |
| 100 // Vibrate for 1 second | |
| 101 // Wait for 1 second | |
| 102 // Vibrate for 3 seconds | |
| 103 // Wait for 1 second | |
| 104 // Vibrate for 5 seconds | |
| 105 navigator.vibrate([1000, 1000, 3000, 1000, 5000]); | |
| 106 | |
| 107 ####Windows Phone 8 Quirks | |
| 108 | |
| 109 - vibrate(pattern) falls back on vibrate with default duration | |
| 110 | |
| 111 ###Cancel vibration (not supported in iOS) | |
| 112 | |
| 113 Immediately cancels any currently running vibration. | |
| 114 | |
| 115 navigator.vibrate(0) | |
| 116 | |
| 117 or | |
| 118 | |
| 119 navigator.vibrate([]) | |
| 120 | |
| 121 or | |
| 122 | |
| 123 navigator.vibrate([0]) | |
| 124 | |
| 125 Passing in a parameter of 0, an empty array, or an array with one element of value 0 will cancel any vibrations. | |
| 126 | |
| 127 ## *notification.vibrate (deprecated) | |
| 128 | |
| 129 Vibrates the device for a given amount of time. | |
| 130 | |
| 131 navigator.notification.vibrate(time) | |
| 132 | |
| 133 - __time__: Milliseconds to vibrate the device. _(Number)_ | |
| 134 | |
| 135 ### Example | |
| 136 | |
| 137 // Vibrate for 2.5 seconds | |
| 138 navigator.notification.vibrate(2500); | |
| 139 | |
| 140 ### iOS Quirks | |
| 141 | |
| 142 - __time__: Ignores the specified time and vibrates for a pre-set amount of time. | |
| 143 | |
| 144 navigator.notification.vibrate(); | |
| 145 navigator.notification.vibrate(2500); // 2500 is ignored | |
| 146 | |
| 147 ## *notification.vibrateWithPattern (deprecated) | |
| 148 | |
| 149 Vibrates the device with a given pattern. | |
| 150 | |
| 151 navigator.notification.vibrateWithPattern(pattern, repeat) | |
| 152 | |
| 153 - __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_ | |
| 154 - __repeat__: Optional index into the pattern array at which to start repeating (will repeat until canceled), or -1 for no repetition (default). _(Number)_ | |
| 155 | |
| 156 ### Example | |
| 157 | |
| 158 // Immediately start vibrating | |
| 159 // vibrate for 100ms, | |
| 160 // wait for 100ms, | |
| 161 // vibrate for 200ms, | |
| 162 // wait for 100ms, | |
| 163 // vibrate for 400ms, | |
| 164 // wait for 100ms, | |
| 165 // vibrate for 800ms, | |
| 166 // (do not repeat) | |
| 167 navigator.notification.vibrateWithPattern([0, 100, 100, 200, 100, 400, 100, 800]); | |
| 168 | |
| 169 ## *notification.cancelVibration (deprecated) | |
| 170 | |
| 171 Immediately cancels any currently running vibration. | |
| 172 | |
| 173 navigator.notification.cancelVibration() | |
| 174 | |
| 175 *Note - due to alignment with w3c spec, the starred methods will be phased out |
