droidcon: Touchgui/plugins/org.apache.cordova.vibration/doc/index.md@e8ccd40d0ef6

     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

    10       http://www.apache.org/licenses/LICENSE-2.0

    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 -->

    20 # org.apache.cordova.vibration

    22 This plugin aligns with the W3C vibration specification http://www.w3.org/TR/vibration/

    24 This plugin provides a way to vibrate the device.

    26 This plugin defines global objects including `navigator.vibrate`.

    28 Although in the global scope, they are not available until after the `deviceready` event.

    30     document.addEventListener("deviceready", onDeviceReady, false);

    31     function onDeviceReady() {

    32         console.log(navigator.vibrate);

    33     }

    35 ## Installation

    37     cordova plugin add org.apache.cordova.vibration

    39 ## Supported Platforms

    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

    50 navigator.notification.vibrateWithPattern,<br />navigator.notification.cancelVibration

    51 - Android

    52 - Windows Phone 8

    54 ## vibrate (recommended)

    56 This function has three different functionalities based on parameters passed to it.

    58 ###Standard vibrate

    60 Vibrates the device for a given amount of time.

    62     navigator.vibrate(time)

    64 or

    66     navigator.vibrate([time])

    69 -__time__: Milliseconds to vibrate the device. _(Number)_

    71 ####Example

    73     // Vibrate for 3 seconds

    74     navigator.vibrate(3000);

    76     // Vibrate for 3 seconds

    77     navigator.vibrate([3000]);

    79 ####iOS Quirks

    81 - __time__: Ignores the specified time and vibrates for a pre-set amount of time.

    83     navigator.vibrate(3000); // 3000 is ignored

    85 ####Windows and Blackberry Quirks

    87 - __time__: Max time is 5000ms (5s) and min time is 1ms

    89     navigator.vibrate(8000); // will be truncated to 5000

    91 ###Vibrate with a pattern (Android and Windows only)

    92 Vibrates the device with a given pattern

    94     navigator.vibrate(pattern);

    96 - __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_

    98 ####Example

   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]);

   107 ####Windows Phone 8 Quirks

   109 - vibrate(pattern) falls back on vibrate with default duration

   111 ###Cancel vibration (not supported in iOS)

   113 Immediately cancels any currently running vibration.

   115     navigator.vibrate(0)

   117 or

   119     navigator.vibrate([])

   121 or

   123     navigator.vibrate([0])

   125 Passing in a parameter of 0, an empty array, or an array with one element of value 0 will cancel any vibrations.

   127 ## *notification.vibrate (deprecated)

   129 Vibrates the device for a given amount of time.

   131     navigator.notification.vibrate(time)

   133 - __time__: Milliseconds to vibrate the device. _(Number)_

   135 ### Example

   137     // Vibrate for 2.5 seconds

   138     navigator.notification.vibrate(2500);

   140 ### iOS Quirks

   142 - __time__: Ignores the specified time and vibrates for a pre-set amount of time.

   144         navigator.notification.vibrate();

   145         navigator.notification.vibrate(2500);   // 2500 is ignored

   147 ## *notification.vibrateWithPattern (deprecated)

   149 Vibrates the device with a given pattern.

   151     navigator.notification.vibrateWithPattern(pattern, repeat)

   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)_

   156 ### Example

   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]);

   169 ## *notification.cancelVibration (deprecated)

   171 Immediately cancels any currently running vibration.

   173     navigator.notification.cancelVibration()

   175 *Note - due to alignment with w3c spec, the starred methods will be phased out

droidcon / file revision

Touchgui/plugins/org.apache.cordova.vibration/doc/index.md@e8ccd40d0ef6

Touchgui/plugins/org.apache.cordova.vibration/doc/index.md