http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-inappbrowser.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-inappbrowser.md b/www/docs/en/6.x/gen/cordova-plugin-inappbrowser.md new file mode 100644 index 0000000..a1c4b3a --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-inappbrowser.md @@ -0,0 +1,403 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-inappbrowser/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-inappbrowser/index.html +plugin_name: cordova-plugin-inappbrowser +plugin_version: master +--- + +<!-- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +[](https://travis-ci.org/apache/cordova-plugin-inappbrowser) + +# cordova-plugin-inappbrowser + +This plugin provides a web browser view that displays when calling `cordova.InAppBrowser.open()`. + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes'); + +The `cordova.InAppBrowser.open()` function is defined to be a drop-in replacement +for the `window.open()` function. Existing `window.open()` calls can use the +InAppBrowser window, by replacing window.open: + + window.open = cordova.InAppBrowser.open; + +The InAppBrowser window behaves like a standard web browser, +and can't access Cordova APIs. For this reason, the InAppBrowser is recommended +if you need to load third-party (untrusted) content, instead of loading that +into the main Cordova webview. The InAppBrowser is not subject to the +whitelist, nor is opening links in the system browser. + +The InAppBrowser provides by default its own GUI controls for the user (back, +forward, done). + +For backwards compatibility, this plugin also hooks `window.open`. +However, the plugin-installed hook of `window.open` can have unintended side +effects (especially if this plugin is included only as a dependency of another +plugin). The hook of `window.open` will be removed in a future major release. +Until the hook is removed from the plugin, apps can manually restore the default +behaviour: + + delete window.open // Reverts the call back to it's prototype's default + +Although `window.open` is in the global scope, InAppBrowser is not available until after the `deviceready` event. + + document.addEventListener("deviceready", onDeviceReady, false); + function onDeviceReady() { + console.log("window.open works well"); + } + +Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20InAppBrowser%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC) + + + +## Installation + + cordova plugin add cordova-plugin-inappbrowser + +If you want all page loads in your app to go through the InAppBrowser, you can +simply hook `window.open` during initialization. For example: + + document.addEventListener("deviceready", onDeviceReady, false); + function onDeviceReady() { + window.open = cordova.InAppBrowser.open; + } + +## cordova.InAppBrowser.open + +Opens a URL in a new `InAppBrowser` instance, the current browser +instance, or the system browser. + + var ref = cordova.InAppBrowser.open(url, target, options); + +- __ref__: Reference to the `InAppBrowser` window. _(InAppBrowser)_ + +- __url__: The URL to load _(String)_. Call `encodeURI()` on this if the URL contains Unicode characters. + +- __target__: The target in which to load the URL, an optional parameter that defaults to `_self`. _(String)_ + + - `_self`: Opens in the Cordova WebView if the URL is in the white list, otherwise it opens in the `InAppBrowser`. + - `_blank`: Opens in the `InAppBrowser`. + - `_system`: Opens in the system's web browser. + +- __options__: Options for the `InAppBrowser`. Optional, defaulting to: `location=yes`. _(String)_ + + The `options` string must not contain any blank space, and each feature's name/value pairs must be separated by a comma. Feature names are case insensitive. All platforms support the value below: + + - __location__: Set to `yes` or `no` to turn the `InAppBrowser`'s location bar on or off. + + Android only: + + - __hidden__: set to `yes` to create the browser and load the page, but not show it. The loadstop event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally. + - __clearcache__: set to `yes` to have the browser's cookie cache cleared before the new window is opened + - __clearsessioncache__: set to `yes` to have the session cookie cache cleared before the new window is opened + - __zoom__: set to `yes` to show Android browser's zoom controls, set to `no` to hide them. Default value is `yes`. + - __hardwareback__: set to `yes` to use the hardware back button to navigate backwards through the `InAppBrowser`'s history. If there is no previous page, the `InAppBrowser` will close. The default value is `yes`, so you must set it to `no` if you want the back button to simply close the InAppBrowser. + - __mediaPlaybackRequiresUserAction__: Set to `yes` to prevent HTML5 audio or video from autoplaying (defaults to `no`). + + iOS only: + + - __closebuttoncaption__: set to a string to use as the __Done__ button's caption. Note that you need to localize this value yourself. + - __disallowoverscroll__: Set to `yes` or `no` (default is `no`). Turns on/off the UIWebViewBounce property. + - __hidden__: set to `yes` to create the browser and load the page, but not show it. The loadstop event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally. + - __clearcache__: set to `yes` to have the browser's cookie cache cleared before the new window is opened + - __clearsessioncache__: set to `yes` to have the session cookie cache cleared before the new window is opened + - __toolbar__: set to `yes` or `no` to turn the toolbar on or off for the InAppBrowser (defaults to `yes`) + - __enableViewportScale__: Set to `yes` or `no` to prevent viewport scaling through a meta tag (defaults to `no`). + - __mediaPlaybackRequiresUserAction__: Set to `yes` to prevent HTML5 audio or video from autoplaying (defaults to `no`). + - __allowInlineMediaPlayback__: Set to `yes` or `no` to allow in-line HTML5 media playback, displaying within the browser window rather than a device-specific playback interface. The HTML's `video` element must also include the `webkit-playsinline` attribute (defaults to `no`) + - __keyboardDisplayRequiresUserAction__: Set to `yes` or `no` to open the keyboard when form elements receive focus via JavaScript's `focus()` call (defaults to `yes`). + - __suppressesIncrementalRendering__: Set to `yes` or `no` to wait until all new view content is received before being rendered (defaults to `no`). + - __presentationstyle__: Set to `pagesheet`, `formsheet` or `fullscreen` to set the [presentation style](http://developer.apple.com/library/ios/documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalPresentationStyle) (defaults to `fullscreen`). + - __transitionstyle__: Set to `fliphorizontal`, `crossdissolve` or `coververtical` to set the [transition style](http://developer.apple.com/library/ios/#documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalTransitionStyle) (defaults to `coververtical`). + - __toolbarposition__: Set to `top` or `bottom` (default is `bottom`). Causes the toolbar to be at the top or bottom of the window. + + Windows only: + + - __hidden__: set to `yes` to create the browser and load the page, but not show it. The loadstop event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally. + - __fullscreen__: set to `yes` to create the browser control without a border around it. Please note that if __location=no__ is also specified, there will be no control presented to user to close IAB window. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- Firefox OS +- iOS +- Windows 8 and 8.1 +- Windows Phone 7 and 8 +- Browser + +### Example + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes'); + var ref2 = cordova.InAppBrowser.open(encodeURI('http://ja.m.wikipedia.org/wiki/ãã³ã°ã«'), '_blank', 'location=yes'); + +### Firefox OS Quirks + +As plugin doesn't enforce any design there is a need to add some CSS rules if +opened with `target='_blank'`. The rules might look like these + +``` css +.inAppBrowserWrap { + background-color: rgba(0,0,0,0.75); + color: rgba(235,235,235,1.0); +} +.inAppBrowserWrap menu { + overflow: auto; + list-style-type: none; + padding-left: 0; +} +.inAppBrowserWrap menu li { + font-size: 25px; + height: 25px; + float: left; + margin: 0 10px; + padding: 3px 10px; + text-decoration: none; + color: #ccc; + display: block; + background: rgba(30,30,30,0.50); +} +.inAppBrowserWrap menu li.disabled { + color: #777; +} +``` + +### Windows Quirks + +Windows 8.0, 8.1 and Windows Phone 8.1 don't support remote urls to be opened in the Cordova WebView so remote urls are always showed in the system's web browser if opened with `target='_self'`. + +On Windows 10 if the URL is NOT in the white list and is opened with `target='_self'` it will be showed in the system's web browser instead of InAppBrowser popup. + +Similar to Firefox OS IAB window visual behaviour can be overridden via `inAppBrowserWrap`/`inAppBrowserWrapFullscreen` CSS classes + +### Browser Quirks + +- Plugin is implemented via iframe, + +- Navigation history (`back` and `forward` buttons in LocationBar) is not implemented. + +## InAppBrowser + +The object returned from a call to `cordova.InAppBrowser.open`. + +### Methods + +- addEventListener +- removeEventListener +- close +- show +- executeScript +- insertCSS + +## InAppBrowser.addEventListener + +> Adds a listener for an event from the `InAppBrowser`. + + ref.addEventListener(eventname, callback); + +- __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ + +- __eventname__: the event to listen for _(String)_ + + - __loadstart__: event fires when the `InAppBrowser` starts to load a URL. + - __loadstop__: event fires when the `InAppBrowser` finishes loading a URL. + - __loaderror__: event fires when the `InAppBrowser` encounters an error when loading a URL. + - __exit__: event fires when the `InAppBrowser` window is closed. + +- __callback__: the function that executes when the event fires. The function is passed an `InAppBrowserEvent` object as a parameter. + +### InAppBrowserEvent Properties + +- __type__: the eventname, either `loadstart`, `loadstop`, `loaderror`, or `exit`. _(String)_ + +- __url__: the URL that was loaded. _(String)_ + +- __code__: the error code, only in the case of `loaderror`. _(Number)_ + +- __message__: the error message, only in the case of `loaderror`. _(String)_ + + +### Supported Platforms + +- Amazon Fire OS +- Android +- iOS +- Windows 8 and 8.1 +- Windows Phone 7 and 8 +- Browser + +### Browser Quirks + +`loadstart` and `loaderror` events are not being fired. + +### Quick Example + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes'); + ref.addEventListener('loadstart', function(event) { alert(event.url); }); + +## InAppBrowser.removeEventListener + +> Removes a listener for an event from the `InAppBrowser`. + + ref.removeEventListener(eventname, callback); + +- __ref__: reference to the `InAppBrowser` window. _(InAppBrowser)_ + +- __eventname__: the event to stop listening for. _(String)_ + + - __loadstart__: event fires when the `InAppBrowser` starts to load a URL. + - __loadstop__: event fires when the `InAppBrowser` finishes loading a URL. + - __loaderror__: event fires when the `InAppBrowser` encounters an error loading a URL. + - __exit__: event fires when the `InAppBrowser` window is closed. + +- __callback__: the function to execute when the event fires. +The function is passed an `InAppBrowserEvent` object. + +### Supported Platforms + +- Amazon Fire OS +- Android +- iOS +- Windows 8 and 8.1 +- Windows Phone 7 and 8 +- Browser + +### Quick Example + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes'); + var myCallback = function(event) { alert(event.url); } + ref.addEventListener('loadstart', myCallback); + ref.removeEventListener('loadstart', myCallback); + +## InAppBrowser.close + +> Closes the `InAppBrowser` window. + + ref.close(); + +- __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ + +### Supported Platforms + +- Amazon Fire OS +- Android +- Firefox OS +- iOS +- Windows 8 and 8.1 +- Windows Phone 7 and 8 +- Browser + +### Quick Example + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes'); + ref.close(); + +## InAppBrowser.show + +> Displays an InAppBrowser window that was opened hidden. Calling this has no effect if the InAppBrowser was already visible. + + ref.show(); + +- __ref__: reference to the InAppBrowser window (`InAppBrowser`) + +### Supported Platforms + +- Amazon Fire OS +- Android +- iOS +- Windows 8 and 8.1 +- Browser + +### Quick Example + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'hidden=yes'); + // some time later... + ref.show(); + +## InAppBrowser.executeScript + +> Injects JavaScript code into the `InAppBrowser` window + + ref.executeScript(details, callback); + +- __ref__: reference to the `InAppBrowser` window. _(InAppBrowser)_ + +- __injectDetails__: details of the script to run, specifying either a `file` or `code` key. _(Object)_ + - __file__: URL of the script to inject. + - __code__: Text of the script to inject. + +- __callback__: the function that executes after the JavaScript code is injected. + - If the injected script is of type `code`, the callback executes + with a single parameter, which is the return value of the + script, wrapped in an `Array`. For multi-line scripts, this is + the return value of the last statement, or the last expression + evaluated. + +### Supported Platforms + +- Amazon Fire OS +- Android +- iOS +- Windows 8 and 8.1 +- Browser + +### Quick Example + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes'); + ref.addEventListener('loadstop', function() { + ref.executeScript({file: "myscript.js"}); + }); + +### Browser Quirks + +- only __code__ key is supported. + +### Windows Quirks + +Due to [MSDN docs](https://msdn.microsoft.com/en-us/library/windows.ui.xaml.controls.webview.invokescriptasync.aspx) the invoked script can return only string values, otherwise the parameter, passed to __callback__ will be `[null]`. + +## InAppBrowser.insertCSS + +> Injects CSS into the `InAppBrowser` window. + + ref.insertCSS(details, callback); + +- __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ + +- __injectDetails__: details of the script to run, specifying either a `file` or `code` key. _(Object)_ + - __file__: URL of the stylesheet to inject. + - __code__: Text of the stylesheet to inject. + +- __callback__: the function that executes after the CSS is injected. + +### Supported Platforms + +- Amazon Fire OS +- Android +- iOS +- Windows + +### Quick Example + + var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes'); + ref.addEventListener('loadstop', function() { + ref.insertCSS({file: "mystyles.css"}); + });
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-legacy-whitelist.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-legacy-whitelist.md b/www/docs/en/6.x/gen/cordova-plugin-legacy-whitelist.md new file mode 100644 index 0000000..d010d30 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-legacy-whitelist.md @@ -0,0 +1,37 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-legacy-whitelist/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-legacy-whitelist/index.html +plugin_name: cordova-plugin-legacy-whitelist +plugin_version: master +--- + +<!-- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +# cordova-plugin-legacy-whitelist + +This plugin implements the Cordova 3.6 Whitelist policy for Cordova 4.0. +Please use cordova-plugin-whitelist instead, as it's more secure. + +Supported on: +- cordova-android@4.0.0 +- cordova-ios@4.0.0 + +## Usage: +Use `<access>` tags, just as in previous versions of Cordova. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-media-capture.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-media-capture.md b/www/docs/en/6.x/gen/cordova-plugin-media-capture.md new file mode 100644 index 0000000..f68fd18 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-media-capture.md @@ -0,0 +1,640 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-media-capture/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-media-capture/index.html +plugin_name: cordova-plugin-media-capture +plugin_version: master +--- + +<!-- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +[](https://travis-ci.org/apache/cordova-plugin-media-capture) + +# cordova-plugin-media-capture + +This plugin provides access to the device's audio, image, and video capture capabilities. + +__WARNING__: Collection and use of images, video, or +audio from the device's camera or microphone raises important privacy +issues. Your app's privacy policy should discuss how the app uses +such sensors and whether the data recorded is shared with any other +parties. In addition, if the app's use of the camera or microphone is +not apparent in the user interface, you should provide a just-in-time +notice before the app accesses the camera or microphone (if the +device operating system doesn't do so already). That notice should +provide the same information noted above, as well as obtaining the +user's permission (e.g., by presenting choices for __OK__ and __No +Thanks__). Note that some app marketplaces may require your app to +provide just-in-time notice and obtain permission from the user prior +to accessing the camera or microphone. For more information, please +see the Privacy Guide. + +This plugin defines global `navigator.device.capture` object. + +Although in the global scope, it is not available until after the `deviceready` event. + + document.addEventListener("deviceready", onDeviceReady, false); + function onDeviceReady() { + console.log(navigator.device.capture); + } + +Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Media%20Capture%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC) + +## Installation + + cordova plugin add cordova-plugin-media-capture + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- Browser +- iOS +- Windows Phone 7 and 8 +- Windows 8 +- Windows + +## Objects + +- Capture +- CaptureAudioOptions +- CaptureImageOptions +- CaptureVideoOptions +- CaptureCallback +- CaptureErrorCB +- ConfigurationData +- MediaFile +- MediaFileData + +## Methods + +- capture.captureAudio +- capture.captureImage +- capture.captureVideo +- MediaFile.getFormatData + +## Properties + +- __supportedAudioModes__: The audio recording formats supported by the device. (ConfigurationData[]) + +- __supportedImageModes__: The recording image sizes and formats supported by the device. (ConfigurationData[]) + +- __supportedVideoModes__: The recording video resolutions and formats supported by the device. (ConfigurationData[]) + +## capture.captureAudio + +> Start the audio recorder application and return information about captured audio clip files. + + navigator.device.capture.captureAudio( + CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureAudioOptions options] + ); + +### Description + +Starts an asynchronous operation to capture audio recordings using the +device's default audio recording application. The operation allows +the device user to capture multiple recordings in a single session. + +The capture operation ends when either the user exits the audio +recording application, or the maximum number of recordings specified +by `CaptureAudioOptions.limit` is reached. If no `limit` parameter +value is specified, it defaults to one (1), and the capture operation +terminates after the user records a single audio clip. + +When the capture operation finishes, the `CaptureCallback` executes +with an array of `MediaFile` objects describing each captured audio +clip file. If the user terminates the operation before an audio clip +is captured, the `CaptureErrorCallback` executes with a `CaptureError` +object, featuring the `CaptureError.CAPTURE_NO_MEDIA_FILES` error +code. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Windows 8 +- Windows + +### Example + + // capture callback + var captureSuccess = function(mediaFiles) { + var i, path, len; + for (i = 0, len = mediaFiles.length; i < len; i += 1) { + path = mediaFiles[i].fullPath; + // do something interesting with the file + } + }; + + // capture error callback + var captureError = function(error) { + navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); + }; + + // start audio capture + navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2}); + +### iOS Quirks + +- iOS does not have a default audio recording application, so a simple user interface is provided. + +### Windows Phone 7 and 8 Quirks + +- Windows Phone 7 does not have a default audio recording application, so a simple user interface is provided. + +## capture.captureImage + +> Start the camera application and return information about captured image files. + + navigator.device.capture.captureImage( + CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options] + ); + +### Description + +Starts an asynchronous operation to capture images using the device's +camera application. The operation allows users to capture more than +one image in a single session. + +The capture operation ends either when the user closes the camera +application, or the maximum number of recordings specified by +`CaptureImageOptions.limit` is reached. If no `limit` value is +specified, it defaults to one (1), and the capture operation +terminates after the user captures a single image. + +When the capture operation finishes, it invokes the `CaptureCB` +callback with an array of `MediaFile` objects describing each captured +image file. If the user terminates the operation before capturing an +image, the `CaptureErrorCB` callback executes with a `CaptureError` +object featuring a `CaptureError.CAPTURE_NO_MEDIA_FILES` error code. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- Browser +- iOS +- Windows Phone 7 and 8 +- Windows 8 +- Windows + +### Windows Phone 7 Quirks + +Invoking the native camera application while your device is connected +via Zune does not work, and the error callback executes. + +### Browser Quirks + +Works in Chrome, Firefox and Opera only (since IE and Safari doesn't supports +navigator.getUserMedia API) + +Displaying images using captured file's URL available in Chrome/Opera only. +Firefox stores captured images in IndexedDB storage (see File plugin documentation), +and due to this the only way to show captured image is to read it and show using its DataURL. + +### Example + + // capture callback + var captureSuccess = function(mediaFiles) { + var i, path, len; + for (i = 0, len = mediaFiles.length; i < len; i += 1) { + path = mediaFiles[i].fullPath; + // do something interesting with the file + } + }; + + // capture error callback + var captureError = function(error) { + navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); + }; + + // start image capture + navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2}); + +## capture.captureVideo + +> Start the video recorder application and return information about captured video clip files. + + navigator.device.capture.captureVideo( + CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options] + ); + +### Description + +Starts an asynchronous operation to capture video recordings using the +device's video recording application. The operation allows the user +to capture more than one recordings in a single session. + +The capture operation ends when either the user exits the video +recording application, or the maximum number of recordings specified +by `CaptureVideoOptions.limit` is reached. If no `limit` parameter +value is specified, it defaults to one (1), and the capture operation +terminates after the user records a single video clip. + +When the capture operation finishes, it the `CaptureCB` callback +executes with an array of `MediaFile` objects describing each captured +video clip file. If the user terminates the operation before +capturing a video clip, the `CaptureErrorCB` callback executes with a +`CaptureError` object featuring a +`CaptureError.CAPTURE_NO_MEDIA_FILES` error code. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Windows 8 +- Windows + +### Example + + // capture callback + var captureSuccess = function(mediaFiles) { + var i, path, len; + for (i = 0, len = mediaFiles.length; i < len; i += 1) { + path = mediaFiles[i].fullPath; + // do something interesting with the file + } + }; + + // capture error callback + var captureError = function(error) { + navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); + }; + + // start video capture + navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2}); + + +### BlackBerry 10 Quirks + +- Cordova for BlackBerry 10 attempts to launch the __Video Recorder__ application, provided by RIM, to capture video recordings. The app receives a `CaptureError.CAPTURE_NOT_SUPPORTED` error code if the application is not installed on the device. + + +## CaptureAudioOptions + +> Encapsulates audio capture configuration options. + +### Properties + +- __limit__: The maximum number of audio clips the device user can record in a single capture operation. The value must be greater than or equal to 1 (defaults to 1). + +- __duration__: The maximum duration of an audio sound clip, in seconds. + +### Example + + // limit capture operation to 3 media files, no longer than 10 seconds each + var options = { limit: 3, duration: 10 }; + + navigator.device.capture.captureAudio(captureSuccess, captureError, options); + +### Amazon Fire OS Quirks + +- The `duration` parameter is not supported. Recording lengths cannot be limited programmatically. + +### Android Quirks + +- The `duration` parameter is not supported. Recording lengths can't be limited programmatically. + +### BlackBerry 10 Quirks + +- The `duration` parameter is not supported. Recording lengths can't be limited programmatically. +- The `limit` parameter is not supported, so only one recording can be created for each invocation. + +### iOS Quirks + +- The `limit` parameter is not supported, so only one recording can be created for each invocation. + + +## CaptureImageOptions + +> Encapsulates image capture configuration options. + +### Properties + +- __limit__: The maximum number of images the user can capture in a single capture operation. The value must be greater than or equal to 1 (defaults to 1). + +### Example + + // limit capture operation to 3 images + var options = { limit: 3 }; + + navigator.device.capture.captureImage(captureSuccess, captureError, options); + +### iOS Quirks + +- The __limit__ parameter is not supported, and only one image is taken per invocation. + + +## CaptureVideoOptions + +> Encapsulates video capture configuration options. + +### Properties + +- __limit__: The maximum number of video clips the device's user can capture in a single capture operation. The value must be greater than or equal to 1 (defaults to 1). + +- __duration__: The maximum duration of a video clip, in seconds. + +### Example + + // limit capture operation to 3 video clips + var options = { limit: 3 }; + + navigator.device.capture.captureVideo(captureSuccess, captureError, options); + +### BlackBerry 10 Quirks + +- The __duration__ property is ignored, so the length of recordings can't be limited programmatically. + +### iOS Quirks + +- The __limit__ property is ignored. Only one video is recorded per invocation. + +### Android Quirks + +- Android supports an additional __quality__ property, to allow capturing video at different qualities. A value of `1` ( the default ) means high quality and value of `0` means low quality, suitable for MMS messages. + See [here](http://developer.android.com/reference/android/provider/MediaStore.html#EXTRA_VIDEO_QUALITY) for more details. + +### Example ( Android w/ quality ) + + // limit capture operation to 1 video clip of low quality + var options = { limit: 1, quality: 0 }; + navigator.device.capture.captureVideo(captureSuccess, captureError, options); + + +## CaptureCB + +> Invoked upon a successful media capture operation. + + function captureSuccess( MediaFile[] mediaFiles ) { ... }; + +### Description + +This function executes after a successful capture operation completes. +At this point a media file has been captured, and either the user has +exited the media capture application, or the capture limit has been +reached. + +Each `MediaFile` object describes a captured media file. + +### Example + + // capture callback + function captureSuccess(mediaFiles) { + var i, path, len; + for (i = 0, len = mediaFiles.length; i < len; i += 1) { + path = mediaFiles[i].fullPath; + // do something interesting with the file + } + }; + +## CaptureError + +> Encapsulates the error code resulting from a failed media capture operation. + +### Properties + +- __code__: One of the pre-defined error codes listed below. + +### Constants + +- `CaptureError.CAPTURE_INTERNAL_ERR`: The camera or microphone failed to capture image or sound. + +- `CaptureError.CAPTURE_APPLICATION_BUSY`: The camera or audio capture application is currently serving another capture request. + +- `CaptureError.CAPTURE_INVALID_ARGUMENT`: Invalid use of the API (e.g., the value of `limit` is less than one). + +- `CaptureError.CAPTURE_NO_MEDIA_FILES`: The user exits the camera or audio capture application before capturing anything. + +- `CaptureError.CAPTURE_NOT_SUPPORTED`: The requested capture operation is not supported. + +## CaptureErrorCB + +> Invoked if an error occurs during a media capture operation. + + function captureError( CaptureError error ) { ... }; + +### Description + +This function executes if an error occurs when trying to launch a +media capture operation. Failure scenarios include when the capture +application is busy, a capture operation is already taking place, or +the user cancels the operation before any media files are captured. + +This function executes with a `CaptureError` object containing an +appropriate error `code`. + +### Example + + // capture error callback + var captureError = function(error) { + navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); + }; + +## ConfigurationData + +> Encapsulates a set of media capture parameters that a device supports. + +### Description + +Describes media capture modes supported by the device. The +configuration data includes the MIME type, and capture dimensions for +video or image capture. + +The MIME types should adhere to [RFC2046](http://www.ietf.org/rfc/rfc2046.txt). Examples: + +- `video/3gpp` +- `video/quicktime` +- `image/jpeg` +- `audio/amr` +- `audio/wav` + +### Properties + +- __type__: The ASCII-encoded lowercase string representing the media type. (DOMString) + +- __height__: The height of the image or video in pixels. The value is zero for sound clips. (Number) + +- __width__: The width of the image or video in pixels. The value is zero for sound clips. (Number) + +### Example + + // retrieve supported image modes + var imageModes = navigator.device.capture.supportedImageModes; + + // Select mode that has the highest horizontal resolution + var width = 0; + var selectedmode; + for each (var mode in imageModes) { + if (mode.width > width) { + width = mode.width; + selectedmode = mode; + } + } + +Not supported by any platform. All configuration data arrays are empty. + +## MediaFile.getFormatData + +> Retrieves format information about the media capture file. + + mediaFile.getFormatData( + MediaFileDataSuccessCB successCallback, + [MediaFileDataErrorCB errorCallback] + ); + +### Description + +This function asynchronously attempts to retrieve the format +information for the media file. If successful, it invokes the +`MediaFileDataSuccessCB` callback with a `MediaFileData` object. If +the attempt fails, this function invokes the `MediaFileDataErrorCB` +callback. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Windows 8 +- Windows + +### Amazon Fire OS Quirks + +The API to access media file format information is limited, so not all +`MediaFileData` properties are supported. + +### BlackBerry 10 Quirks + +Does not provide an API for information about media files, so all +`MediaFileData` objects return with default values. + +### Android Quirks + +The API to access media file format information is limited, so not all +`MediaFileData` properties are supported. + +### iOS Quirks + +The API to access media file format information is limited, so not all +`MediaFileData` properties are supported. + +## MediaFile + +> Encapsulates properties of a media capture file. + +### Properties + +- __name__: The name of the file, without path information. (DOMString) + +- __fullPath__: The full path of the file, including the name. (DOMString) + +- __type__: The file's mime type (DOMString) + +- __lastModifiedDate__: The date and time when the file was last modified. (Date) + +- __size__: The size of the file, in bytes. (Number) + +### Methods + +- __MediaFile.getFormatData__: Retrieves the format information of the media file. + +## MediaFileData + +> Encapsulates format information about a media file. + +### Properties + +- __codecs__: The actual format of the audio and video content. (DOMString) + +- __bitrate__: The average bitrate of the content. The value is zero for images. (Number) + +- __height__: The height of the image or video in pixels. The value is zero for audio clips. (Number) + +- __width__: The width of the image or video in pixels. The value is zero for audio clips. (Number) + +- __duration__: The length of the video or sound clip in seconds. The value is zero for images. (Number) + +### BlackBerry 10 Quirks + +No API provides format information for media files, so the +`MediaFileData` object returned by `MediaFile.getFormatData` features +the following default values: + +- __codecs__: Not supported, and returns `null`. + +- __bitrate__: Not supported, and returns zero. + +- __height__: Not supported, and returns zero. + +- __width__: Not supported, and returns zero. + +- __duration__: Not supported, and returns zero. + +### Amazon Fire OS Quirks + +Supports the following `MediaFileData` properties: + +- __codecs__: Not supported, and returns `null`. + +- __bitrate__: Not supported, and returns zero. + +- __height__: Supported: image and video files only. + +- __width__: Supported: image and video files only. + +- __duration__: Supported: audio and video files only + +### Android Quirks + +Supports the following `MediaFileData` properties: + +- __codecs__: Not supported, and returns `null`. + +- __bitrate__: Not supported, and returns zero. + +- __height__: Supported: image and video files only. + +- __width__: Supported: image and video files only. + +- __duration__: Supported: audio and video files only. + +### iOS Quirks + +Supports the following `MediaFileData` properties: + +- __codecs__: Not supported, and returns `null`. + +- __bitrate__: Supported on iOS4 devices for audio only. Returns zero for images and videos. + +- __height__: Supported: image and video files only. + +- __width__: Supported: image and video files only. + +- __duration__: Supported: audio and video files only. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-media.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-media.md b/www/docs/en/6.x/gen/cordova-plugin-media.md new file mode 100644 index 0000000..7425df9 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-media.md @@ -0,0 +1,525 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-media/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-media/index.html +plugin_name: cordova-plugin-media +plugin_version: master +--- + +<!-- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +[](https://travis-ci.org/apache/cordova-plugin-media) + +# cordova-plugin-media + + +This plugin provides the ability to record and play back audio files on a device. + +__NOTE__: The current implementation does not adhere to a W3C +specification for media capture, and is provided for convenience only. +A future implementation will adhere to the latest W3C specification +and may deprecate the current APIs. + +This plugin defines a global `Media` Constructor. + +Although in the global scope, it is not available until after the `deviceready` event. + + document.addEventListener("deviceready", onDeviceReady, false); + function onDeviceReady() { + console.log(Media); + } + +Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Media%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC) + + +## Installation + + cordova plugin add cordova-plugin-media + +## Supported Platforms + +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Tizen +- Windows 8 +- Windows +- Browser + +## Windows Phone Quirks + +- Only one media file can be played back at a time. + +## Media + + var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]); + +### Parameters + +- __src__: A URI containing the audio content. _(DOMString)_ + +- __mediaSuccess__: (Optional) The callback that executes after a `Media` object has completed the current play, record, or stop action. _(Function)_ + +- __mediaError__: (Optional) The callback that executes if an error occurs. _(Function)_ + +- __mediaStatus__: (Optional) The callback that executes to indicate status changes. _(Function)_ + +__NOTE__: `cdvfile` path is supported as `src` parameter: +```javascript +var my_media = new Media('cdvfile://localhost/temporary/recording.mp3', ...); +``` + +### Constants + +The following constants are reported as the only parameter to the +`mediaStatus` callback: + +- `Media.MEDIA_NONE` = 0; +- `Media.MEDIA_STARTING` = 1; +- `Media.MEDIA_RUNNING` = 2; +- `Media.MEDIA_PAUSED` = 3; +- `Media.MEDIA_STOPPED` = 4; + +### Methods + +- `media.getCurrentPosition`: Returns the current position within an audio file. + +- `media.getDuration`: Returns the duration of an audio file. + +- `media.play`: Start or resume playing an audio file. + +- `media.pause`: Pause playback of an audio file. + +- `media.release`: Releases the underlying operating system's audio resources. + +- `media.seekTo`: Moves the position within the audio file. + +- `media.setVolume`: Set the volume for audio playback. + +- `media.startRecord`: Start recording an audio file. + +- `media.stopRecord`: Stop recording an audio file. + +- `media.stop`: Stop playing an audio file. + +### Additional ReadOnly Parameters + +- __position__: The position within the audio playback, in seconds. + - Not automatically updated during play; call `getCurrentPosition` to update. + +- __duration__: The duration of the media, in seconds. + + +## media.getCurrentPosition + +Returns the current position within an audio file. Also updates the `Media` object's `position` parameter. + + media.getCurrentPosition(mediaSuccess, [mediaError]); + +### Parameters + +- __mediaSuccess__: The callback that is passed the current position in seconds. + +- __mediaError__: (Optional) The callback to execute if an error occurs. + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + + // Update media position every second + var mediaTimer = setInterval(function () { + // get media position + my_media.getCurrentPosition( + // success callback + function (position) { + if (position > -1) { + console.log((position) + " sec"); + } + }, + // error callback + function (e) { + console.log("Error getting pos=" + e); + } + ); + }, 1000); + + +## media.getDuration + +Returns the duration of an audio file in seconds. If the duration is unknown, it returns a value of -1. + + + media.getDuration(); + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + + // Get duration + var counter = 0; + var timerDur = setInterval(function() { + counter = counter + 100; + if (counter > 2000) { + clearInterval(timerDur); + } + var dur = my_media.getDuration(); + if (dur > 0) { + clearInterval(timerDur); + document.getElementById('audio_duration').innerHTML = (dur) + " sec"; + } + }, 100); + + +## media.pause + +Pauses playing an audio file. + + media.pause(); + + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function () { console.log("playAudio():Audio Success"); }, + // error callback + function (err) { console.log("playAudio():Audio Error: " + err); } + ); + + // Play audio + my_media.play(); + + // Pause after 10 seconds + setTimeout(function () { + my_media.pause(); + }, 10000); + } + + +## media.play + +Starts or resumes playing an audio file. + + media.play(); + + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function () { + console.log("playAudio():Audio Success"); + }, + // error callback + function (err) { + console.log("playAudio():Audio Error: " + err); + } + ); + // Play audio + my_media.play(); + } + + +### iOS Quirks + +- __numberOfLoops__: Pass this option to the `play` method to specify + the number of times you want the media file to play, e.g.: + + var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3";) + myMedia.play({ numberOfLoops: 2 }) + +- __playAudioWhenScreenIsLocked__: Pass in this option to the `play` + method to specify whether you want to allow playback when the screen + is locked. If set to `true` (the default value), the state of the + hardware mute button is ignored, e.g.: + + var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3";) + myMedia.play({ playAudioWhenScreenIsLocked : false }) + +- __order of file search__: When only a file name or simple path is + provided, iOS searches in the `www` directory for the file, then in + the application's `documents/tmp` directory: + + var myMedia = new Media("audio/beer.mp3") + myMedia.play() // first looks for file in www/audio/beer.mp3 then in <application>/documents/tmp/audio/beer.mp3 + +## media.release + +Releases the underlying operating system's audio resources. +This is particularly important for Android, since there are a finite amount of +OpenCore instances for media playback. Applications should call the `release` +function for any `Media` resource that is no longer needed. + + media.release(); + + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + + my_media.play(); + my_media.stop(); + my_media.release(); + + +## media.seekTo + +Sets the current position within an audio file. + + media.seekTo(milliseconds); + +### Parameters + +- __milliseconds__: The position to set the playback position within the audio, in milliseconds. + + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + my_media.play(); + // SeekTo to 10 seconds after 5 seconds + setTimeout(function() { + my_media.seekTo(10000); + }, 5000); + + +### BlackBerry 10 Quirks + +- Not supported on BlackBerry OS 5 devices. + +## media.setVolume + +Set the volume for an audio file. + + media.setVolume(volume); + +### Parameters + +- __volume__: The volume to set for playback. The value must be within the range of 0.0 to 1.0. + +### Supported Platforms + +- Android +- iOS + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function() { + console.log("playAudio():Audio Success"); + }, + // error callback + function(err) { + console.log("playAudio():Audio Error: "+err); + }); + + // Play audio + my_media.play(); + + // Mute volume after 2 seconds + setTimeout(function() { + my_media.setVolume('0.0'); + }, 2000); + + // Set volume to 1.0 after 5 seconds + setTimeout(function() { + my_media.setVolume('1.0'); + }, 5000); + } + + +## media.startRecord + +Starts recording an audio file. + + media.startRecord(); + +### Supported Platforms + +- Android +- iOS +- Windows Phone 7 and 8 +- Windows + +### Quick Example + + // Record audio + // + function recordAudio() { + var src = "myrecording.mp3"; + var mediaRec = new Media(src, + // success callback + function() { + console.log("recordAudio():Audio Success"); + }, + + // error callback + function(err) { + console.log("recordAudio():Audio Error: "+ err.code); + }); + + // Record audio + mediaRec.startRecord(); + } + + +### Android Quirks + +- Android devices record audio in Adaptive Multi-Rate format. The specified file should end with a _.amr_ extension. +- The hardware volume controls are wired up to the media volume while any Media objects are alive. Once the last created Media object has `release()` called on it, the volume controls revert to their default behaviour. The controls are also reset on page navigation, as this releases all Media objects. + +### iOS Quirks + +- iOS only records to files of type _.wav_ and returns an error if the file name extension is not correct. + +- If a full path is not provided, the recording is placed in the application's `documents/tmp` directory. This can be accessed via the `File` API using `LocalFileSystem.TEMPORARY`. Any subdirectory specified at record time must already exist. + +- Files can be recorded and played back using the documents URI: + + var myMedia = new Media("documents://beer.mp3") + +### Windows Quirks + +- Windows devices can use MP3, M4A and WMA formats for recorded audio. However in most cases it is not possible to use MP3 for audio recording on _Windows Phone 8.1_ devices, because an MP3 encoder is [not shipped with Windows Phone](https://msdn.microsoft.com/en-us/library/windows/apps/windows.media.mediaproperties.mediaencodingprofile.createmp3.aspx). + +- If a full path is not provided, the recording is placed in the `AppData/temp` directory. This can be accessed via the `File` API using `LocalFileSystem.TEMPORARY` or `ms-appdata:///temp/<filename>` URI. + +- Any subdirectory specified at record time must already exist. + +### Tizen Quirks + +- Not supported on Tizen devices. + +## media.stop + +Stops playing an audio file. + + media.stop(); + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function() { + console.log("playAudio():Audio Success"); + }, + // error callback + function(err) { + console.log("playAudio():Audio Error: "+err); + } + ); + + // Play audio + my_media.play(); + + // Pause after 10 seconds + setTimeout(function() { + my_media.stop(); + }, 10000); + } + + +## media.stopRecord + +Stops recording an audio file. + + media.stopRecord(); + +### Supported Platforms + +- Android +- iOS +- Windows Phone 7 and 8 +- Windows + +### Quick Example + + // Record audio + // + function recordAudio() { + var src = "myrecording.mp3"; + var mediaRec = new Media(src, + // success callback + function() { + console.log("recordAudio():Audio Success"); + }, + + // error callback + function(err) { + console.log("recordAudio():Audio Error: "+ err.code); + } + ); + + // Record audio + mediaRec.startRecord(); + + // Stop recording after 10 seconds + setTimeout(function() { + mediaRec.stopRecord(); + }, 10000); + } + + +### Tizen Quirks + +- Not supported on Tizen devices. + +## MediaError + +A `MediaError` object is returned to the `mediaError` callback +function when an error occurs. + +### Properties + +- __code__: One of the predefined error codes listed below. + +- __message__: An error message describing the details of the error. + +### Constants + +- `MediaError.MEDIA_ERR_ABORTED` = 1 +- `MediaError.MEDIA_ERR_NETWORK` = 2 +- `MediaError.MEDIA_ERR_DECODE` = 3 +- `MediaError.MEDIA_ERR_NONE_SUPPORTED` = 4 http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-network-information.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-network-information.md b/www/docs/en/6.x/gen/cordova-plugin-network-information.md new file mode 100644 index 0000000..a981161 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-network-information.md @@ -0,0 +1,220 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-network-information/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-network-information/index.html +plugin_name: cordova-plugin-network-information +plugin_version: master +--- + +<!-- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +[](https://travis-ci.org/apache/cordova-plugin-network-information) + +# cordova-plugin-network-information + + +This plugin provides an implementation of an old version of the +[Network Information API](http://www.w3.org/TR/2011/WD-netinfo-api-20110607/). +It provides information about the device's cellular and +wifi connection, and whether the device has an internet connection. + +Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cordova issue tracker]. + +## Installation + + cordova plugin add cordova-plugin-network-information + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- Browser +- iOS +- Windows Phone 7 and 8 +- Tizen +- Windows +- Firefox OS + +# Connection + +> The `connection` object, exposed via `navigator.connection`, provides information about the device's cellular and wifi connection. + +## Properties + +- connection.type + +## Constants + +- Connection.UNKNOWN +- Connection.ETHERNET +- Connection.WIFI +- Connection.CELL_2G +- Connection.CELL_3G +- Connection.CELL_4G +- Connection.CELL +- Connection.NONE + +## connection.type + +This property offers a fast way to determine the device's network +connection state, and type of connection. + +### Quick Example + + function checkConnection() { + var networkState = navigator.connection.type; + + var states = {}; + states[Connection.UNKNOWN] = 'Unknown connection'; + states[Connection.ETHERNET] = 'Ethernet connection'; + states[Connection.WIFI] = 'WiFi connection'; + states[Connection.CELL_2G] = 'Cell 2G connection'; + states[Connection.CELL_3G] = 'Cell 3G connection'; + states[Connection.CELL_4G] = 'Cell 4G connection'; + states[Connection.CELL] = 'Cell generic connection'; + states[Connection.NONE] = 'No network connection'; + + alert('Connection type: ' + states[networkState]); + } + + checkConnection(); + + +### API Change + +Until Cordova 2.3.0, the `Connection` object was accessed via +`navigator.network.connection`, after which it was changed to +`navigator.connection` to match the W3C specification. It's still +available at its original location, but is deprecated and will +eventually be removed. + +### iOS Quirks + +- <iOS7 can't detect the type of cellular network connection. + - `navigator.connection.type` is set to `Connection.CELL` for all cellular data. + +### Windows Phone Quirks + +- When running in the emulator, always detects `navigator.connection.type` as `Connection.UNKNOWN`. + +- Windows Phone can't detect the type of cellular network connection. + - `navigator.connection.type` is set to `Connection.CELL` for all cellular data. + +### Windows Quirks + +- When running in the Phone 8.1 emulator, always detects `navigator.connection.type` as `Connection.ETHERNET`. + +### Tizen Quirks + +- Tizen can only detect a WiFi or cellular connection. + - `navigator.connection.type` is set to `Connection.CELL_2G` for all cellular data. + +### Firefox OS Quirks + +- Firefox OS can't detect the type of cellular network connection. + - `navigator.connection.type` is set to `Connection.CELL` for all cellular data. + +### Browser Quirks + +- Browser can't detect the type of network connection. +`navigator.connection.type` is always set to `Connection.UNKNOWN` when online. + +# Network-related Events + +## offline + +The event fires when an application goes offline, and the device is +not connected to the Internet. + + document.addEventListener("offline", yourCallbackFunction, false); + +### Details + +The `offline` event fires when a previously connected device loses a +network connection so that an application can no longer access the +Internet. It relies on the same information as the Connection API, +and fires when the value of `connection.type` becomes `NONE`. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +### Quick Example + + document.addEventListener("offline", onOffline, false); + + function onOffline() { + // Handle the offline event + } + + +### iOS Quirks + +During initial startup, the first offline event (if applicable) takes at least a second to fire. + +### Windows Phone 7 Quirks + +When running in the Emulator, the `connection.status` is always unknown, so this event does _not_ fire. + +### Windows Phone 8 Quirks + +The Emulator reports the connection type as `Cellular`, which does not change, so the event does _not_ fire. + +## online + +This event fires when an application goes online, and the device +becomes connected to the Internet. + + document.addEventListener("online", yourCallbackFunction, false); + +### Details + +The `online` event fires when a previously unconnected device receives +a network connection to allow an application access to the Internet. +It relies on the same information as the Connection API, +and fires when the `connection.type` changes from `NONE` to any other +value. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +### Quick Example + + document.addEventListener("online", onOnline, false); + + function onOnline() { + // Handle the online event + } + + +### iOS Quirks + +During initial startup, the first `online` event (if applicable) takes +at least a second to fire, prior to which `connection.type` is +`UNKNOWN`. + +### Windows Phone 7 Quirks + +When running in the Emulator, the `connection.status` is always unknown, so this event does _not_ fire. + +### Windows Phone 8 Quirks + +The Emulator reports the connection type as `Cellular`, which does not change, so events does _not_ fire. + +[Apache Cordova issue tracker]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Network%20Information%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-splashscreen.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-splashscreen.md b/www/docs/en/6.x/gen/cordova-plugin-splashscreen.md new file mode 100644 index 0000000..8f5e9c1 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-splashscreen.md @@ -0,0 +1,181 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-splashscreen/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-splashscreen/index.html +plugin_name: cordova-plugin-splashscreen +plugin_version: master +--- + +<!-- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +[](https://travis-ci.org/apache/cordova-plugin-splashscreen) + +# cordova-plugin-splashscreen + +This plugin displays and hides a splash screen during application launch. + +Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cordova issue tracker]. + +## Installation + + // npm hosted (new) id + cordova plugin add cordova-plugin-splashscreen + + // you may also install directly from this repo + cordova plugin add https://github.com/apache/cordova-plugin-splashscreen.git + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Windows 8 +- Windows +- Browser + +## Preferences + +#### config.xml + +- __SplashScreen__ (string). The resource name which is used for the displaying splash screen. Different platforms use values for this. + + <preference name="SplashScreen" value="resourcename" /> + +- __AutoHideSplashScreen__ (boolean, default to `true`). Indicates wherether hide splash screen automatically or not. Splash screen hidden after amount of time specified in the `SplashScreenDelay` preference. + + <preference name="AutoHideSplashScreen" value="true" /> + +- __SplashScreenDelay__ (number, default to 3000). Amount of time in milliseconds to wait before automatically hide splash screen. + + <preference name="SplashScreenDelay" value="3000" /> + + +### Android Quirks + +In your `config.xml`, you need to add the following preferences: + + <preference name="SplashScreen" value="foo" /> + <preference name="SplashScreenDelay" value="3000" /> + <preference name="SplashMaintainAspectRatio" value="true|false" /> + <preference name="SplashShowOnlyFirstTime" value="true|false" /> + +Where foo is the name of the splashscreen file, preferably a 9 patch file. Make sure to add your splashcreen files to your res/xml directory under the appropriate folders. The second parameter represents how long the splashscreen will appear in milliseconds. It defaults to 3000 ms. See [Icons and Splash Screens](http://cordova.apache.org/docs/en/edge/config_ref_images.md.html) +for more information. + +"SplashMaintainAspectRatio" preference is optional. If set to true, splash screen drawable is not stretched to fit screen, but instead simply "covers" the screen, like CSS "background-size:cover". This is very useful when splash screen images cannot be distorted in any way, for example when they contain scenery or text. This setting works best with images that have large margins (safe areas) that can be safely cropped on screens with different aspect ratios. + +The plugin reloads splash drawable whenever orientation changes, so you can specify different drawables for portrait and landscape orientations. + +"SplashShowOnlyFirstTime" preference is also optional and defaults to `true`. When set to `true` splash screen will only appear on application launch. However, if you plan to use `navigator.app.exitApp()` to close application and force splash screen appear on next launch, you should set this property to `false` (this also applies to closing the App with Back button). + +### Browser Quirks + +You can use the following preferences in your `config.xml`: + + <platform name="browser"> + <preference name="SplashScreen" value="/images/browser/splashscreen.jpg" /> <!-- defaults to "/img/logo.png" --> + <preference name="SplashScreenDelay" value="3000" /> <!-- defaults to "3000" --> + <preference name="SplashScreenBackgroundColor" value="green" /> <!-- defaults to "#464646" --> + <preference name="ShowSplashScreen" value="false" /> <!-- defaults to "true" --> + <preference name="SplashScreenWidth" value="600" /> <!-- defaults to "170" --> + <preference name="SplashScreenHeight" value="300" /> <!-- defaults to "200" --> + </platform> + +__Note__: `SplashScreen` value should be absolute in order to work in a sub-page. + +### Android and iOS Quirks + +- `FadeSplashScreen` (boolean, defaults to `true`): Set to `false` to + prevent the splash screen from fading in and out when its display + state changes. + + <preference name="FadeSplashScreen" value="false"/> + +- `FadeSplashScreenDuration` (float, defaults to `3000`): Specifies the + number of milliseconds for the splash screen fade effect to execute. + + <preference name="FadeSplashScreenDuration" value="3000"/> + +Note also that this value used to be seconds, and not milliseconds, so values less than 30 will still be treated as seconds. ( Consider this a deprecated patch that will disapear in some future version. ) + +_Note_: `FadeSplashScreenDuration` is included into `SplashScreenDelay`, for example if you have `<preference name="SplashScreenDelay" value="3000" />` and `<preference name="FadeSplashScreenDuration" value="1000"/>` defined in `config.xml`: + +- 00:00 - splashscreen is shown +- 00:02 - fading has started +- 00:03 - splashscreen is hidden + +Turning the fading off via `<preference name="FadeSplashScreen" value="false"/>` technically means fading duration to be `0` so that in this example the overall splash delay will still be 3 seconds. + +_Note_: This only applies to the app startup - you need to take the fading timeout into account when manually showing/hiding the splashscreen in the code: + +```javascript +navigator.splashscreen.show(); +window.setTimeout(function () { + navigator.splashscreen.hide(); +}, splashDuration - fadeDuration); +``` + +- `ShowSplashScreenSpinner` (boolean, defaults to `true`): Set to `false` + to hide the splash-screen spinner. + + <preference name="ShowSplashScreenSpinner" value="false"/> + +## Methods + +- splashscreen.show +- splashscreen.hide + +## splashscreen.hide + +Dismiss the splash screen. + + navigator.splashscreen.hide(); + + +### BlackBerry 10, WP8, iOS Quirk + +The `config.xml` file's `AutoHideSplashScreen` setting must be +`false`. To delay hiding the splash screen for two seconds, add a +timer such as the following in the `deviceready` event handler: + + setTimeout(function() { + navigator.splashscreen.hide(); + }, 2000); + +## splashscreen.show + +Displays the splash screen. + + navigator.splashscreen.show(); + + +Your application cannot call `navigator.splashscreen.show()` until the app has +started and the `deviceready` event has fired. But since typically the splash +screen is meant to be visible before your app has started, that would seem to +defeat the purpose of the splash screen. Providing some configuration in +`config.xml` will automatically `show` the splash screen immediately after your +app launch and before it has fully started and received the `deviceready` +event. See [Icons and Splash Screens](http://cordova.apache.org/docs/en/edge/config_ref_images.md.html) +for more information on doing this configuration. For this reason, it is +unlikely you need to call `navigator.splashscreen.show()` to make the splash +screen visible for app startup. + +[Apache Cordova issue tracker]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Splashscreen%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-statusbar.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-statusbar.md b/www/docs/en/6.x/gen/cordova-plugin-statusbar.md new file mode 100644 index 0000000..e7a737e --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-statusbar.md @@ -0,0 +1,313 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-statusbar/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-statusbar/index.html +plugin_name: cordova-plugin-statusbar +plugin_version: master +--- + +<!--- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +[](https://travis-ci.org/apache/cordova-plugin-statusbar) + +# cordova-plugin-statusbar + +StatusBar +====== + +> The `StatusBar` object provides some functions to customize the iOS and Android StatusBar. + +:warning: Report issues on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Statusbar%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC) + + +## Installation + +This installation method requires cordova 5.0+ + + cordova plugin add cordova-plugin-statusbar +Older versions of cordova can still install via the __deprecated__ id + + cordova plugin add org.apache.cordova.statusbar +It is also possible to install via repo url directly ( unstable ) + + cordova plugin add https://github.com/apache/cordova-plugin-statusbar.git + + +Preferences +----------- + +#### config.xml + +- __StatusBarOverlaysWebView__ (boolean, defaults to true). On iOS 7, make the statusbar overlay or not overlay the WebView at startup. + + <preference name="StatusBarOverlaysWebView" value="true" /> + +- __StatusBarBackgroundColor__ (color hex string, no default value). On iOS 7, set the background color of the statusbar by a hex string (#RRGGBB) at startup. If this value is not set, the background color will be transparent. + + <preference name="StatusBarBackgroundColor" value="#000000" /> + +- __StatusBarStyle__ (status bar style, defaults to lightcontent). On iOS 7, set the status bar style. Available options default, lightcontent, blacktranslucent, blackopaque. + + <preference name="StatusBarStyle" value="lightcontent" /> + +### Android Quirks +The Android 5+ guidelines specify using a different color for the statusbar than your main app color (unlike the uniform statusbar color of many iOS 7+ apps), so you may want to set the statusbar color at runtime instead via `StatusBar.backgroundColorByHexString` or `StatusBar.backgroundColorByName`. One way to do that would be: +```js +if (cordova.platformId == 'android') { + StatusBar.backgroundColorByHexString("#333"); +} +``` + +Hiding at startup +----------- + +During runtime you can use the StatusBar.hide function below, but if you want the StatusBar to be hidden at app startup, you must modify your app's Info.plist file. + +Add/edit these two attributes if not present. Set **"Status bar is initially hidden"** to **"YES"** and set **"View controller-based status bar appearance"** to **"NO"**. If you edit it manually without Xcode, the keys and values are: + + + <key>UIStatusBarHidden</key> + <true/> + <key>UIViewControllerBasedStatusBarAppearance</key> + <false/> + + +Methods +------- +This plugin defines global `StatusBar` object. + +Although in the global scope, it is not available until after the `deviceready` event. + + document.addEventListener("deviceready", onDeviceReady, false); + function onDeviceReady() { + console.log(StatusBar); + } + +- StatusBar.overlaysWebView +- StatusBar.styleDefault +- StatusBar.styleLightContent +- StatusBar.styleBlackTranslucent +- StatusBar.styleBlackOpaque +- StatusBar.backgroundColorByName +- StatusBar.backgroundColorByHexString +- StatusBar.hide +- StatusBar.show + +Properties +-------- + +- StatusBar.isVisible + +Permissions +----------- + +#### config.xml + + <feature name="StatusBar"> + <param name="ios-package" value="CDVStatusBar" onload="true" /> + </feature> + +StatusBar.overlaysWebView +================= + +On iOS 7, make the statusbar overlay or not overlay the WebView. + + StatusBar.overlaysWebView(true); + +Description +----------- + +On iOS 7, set to false to make the statusbar appear like iOS 6. Set the style and background color to suit using the other functions. + + +Supported Platforms +------------------- + +- iOS + +Quick Example +------------- + + StatusBar.overlaysWebView(true); + StatusBar.overlaysWebView(false); + +StatusBar.styleDefault +================= + +Use the default statusbar (dark text, for light backgrounds). + + StatusBar.styleDefault(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.styleLightContent +================= + +Use the lightContent statusbar (light text, for dark backgrounds). + + StatusBar.styleLightContent(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.styleBlackTranslucent +================= + +Use the blackTranslucent statusbar (light text, for dark backgrounds). + + StatusBar.styleBlackTranslucent(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.styleBlackOpaque +================= + +Use the blackOpaque statusbar (light text, for dark backgrounds). + + StatusBar.styleBlackOpaque(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + + +StatusBar.backgroundColorByName +================= + +On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by color name. + + StatusBar.backgroundColorByName("red"); + +Supported color names are: + + black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown + + +Supported Platforms +------------------- + +- iOS +- Android 5+ +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.backgroundColorByHexString +================= + +Sets the background color of the statusbar by a hex string. + + StatusBar.backgroundColorByHexString("#C0C0C0"); + +CSS shorthand properties are also supported. + + StatusBar.backgroundColorByHexString("#333"); // => #333333 + StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB + +On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by a hex string (#RRGGBB). + +On WP7 and WP8 you can also specify values as #AARRGGBB, where AA is an alpha value + +Supported Platforms +------------------- + +- iOS +- Android 5+ +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.hide +================= + +Hide the statusbar. + + StatusBar.hide(); + + +Supported Platforms +------------------- + +- iOS +- Android +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.show +================= + +Shows the statusbar. + + StatusBar.show(); + + +Supported Platforms +------------------- + +- iOS +- Android +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + + +StatusBar.isVisible +================= + +Read this property to see if the statusbar is visible or not. + + if (StatusBar.isVisible) { + // do something + } + + +Supported Platforms +------------------- + +- iOS +- Android +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-vibration.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-vibration.md b/www/docs/en/6.x/gen/cordova-plugin-vibration.md new file mode 100644 index 0000000..d7daea0 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-vibration.md @@ -0,0 +1,187 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-vibration/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-vibration/index.html +plugin_name: cordova-plugin-vibration +plugin_version: master +--- + +<!-- +# license: Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +--> + +[](https://travis-ci.org/apache/cordova-plugin-vibration) + +# cordova-plugin-vibration + +This plugin aligns with the W3C vibration specification http://www.w3.org/TR/vibration/ + +This plugin provides a way to vibrate the device. + +This plugin defines global objects including `navigator.vibrate`. + +Although in the global scope, they are not available until after the `deviceready` event. + + document.addEventListener("deviceready", onDeviceReady, false); + function onDeviceReady() { + console.log(navigator.vibrate); + } + +## Installation + + cordova plugin add cordova-plugin-vibration + +## Supported Platforms + +navigator.vibrate,<br /> +navigator.notification.vibrate +- Amazon Fire OS +- Android +- BlackBerry 10 +- Firefox OS +- iOS +- Windows Phone 7 and 8 +- Windows (Windows Phone 8.1 devices only) + +navigator.notification.vibrateWithPattern<br /> +navigator.notification.cancelVibration +- Android +- Windows Phone 8 +- Windows (Windows Phone 8.1 devices only) + +## vibrate (recommended) + +This function has three different functionalities based on parameters passed to it. + +###Standard vibrate + +Vibrates the device for a given amount of time. + + navigator.vibrate(time) + +or + + navigator.vibrate([time]) + + +-__time__: Milliseconds to vibrate the device. _(Number)_ + +####Example + + // Vibrate for 3 seconds + navigator.vibrate(3000); + + // Vibrate for 3 seconds + navigator.vibrate([3000]); + +####iOS Quirks + +- __time__: Ignores the specified time and vibrates for a pre-set amount of time. + + navigator.vibrate(3000); // 3000 is ignored + +####Windows and Blackberry Quirks + +- __time__: Max time is 5000ms (5s) and min time is 1ms + + navigator.vibrate(8000); // will be truncated to 5000 + +###Vibrate with a pattern (Android and Windows only) +Vibrates the device with a given pattern + + navigator.vibrate(pattern); + +- __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_ + +####Example + + // Vibrate for 1 second + // Wait for 1 second + // Vibrate for 3 seconds + // Wait for 1 second + // Vibrate for 5 seconds + navigator.vibrate([1000, 1000, 3000, 1000, 5000]); + +####Windows Phone 8 Quirks + +- vibrate(pattern) falls back on vibrate with default duration + +###Cancel vibration (not supported in iOS) + +Immediately cancels any currently running vibration. + + navigator.vibrate(0) + +or + + navigator.vibrate([]) + +or + + navigator.vibrate([0]) + +Passing in a parameter of 0, an empty array, or an array with one element of value 0 will cancel any vibrations. + +## *notification.vibrate (deprecated) + +Vibrates the device for a given amount of time. + + navigator.notification.vibrate(time) + +- __time__: Milliseconds to vibrate the device. _(Number)_ + +### Example + + // Vibrate for 2.5 seconds + navigator.notification.vibrate(2500); + +### iOS Quirks + +- __time__: Ignores the specified time and vibrates for a pre-set amount of time. + + navigator.notification.vibrate(); + navigator.notification.vibrate(2500); // 2500 is ignored + +## *notification.vibrateWithPattern (deprecated) + +Vibrates the device with a given pattern. + + navigator.notification.vibrateWithPattern(pattern, repeat) + +- __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_ +- __repeat__: Optional index into the pattern array at which to start repeating (will repeat until canceled), or -1 for no repetition (default). _(Number)_ + +### Example + + // Immediately start vibrating + // vibrate for 100ms, + // wait for 100ms, + // vibrate for 200ms, + // wait for 100ms, + // vibrate for 400ms, + // wait for 100ms, + // vibrate for 800ms, + // (do not repeat) + navigator.notification.vibrateWithPattern([0, 100, 100, 200, 100, 400, 100, 800]); + +## *notification.cancelVibration (deprecated) + +Immediately cancels any currently running vibration. + + navigator.notification.cancelVibration() + +*Note - due to alignment with w3c spec, the starred methods will be phased out \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
