[
https://issues.apache.org/jira/browse/CB-10351?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15129220#comment-15129220
]
ASF GitHub Bot commented on CB-10351:
-------------------------------------
Github user riknoll commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/480#discussion_r51649012
--- Diff: www/docs/en/dev/cordova/events/events.md ---
@@ -22,29 +22,560 @@ title: Events
# Events
-> Cordova lifecycle events.
+<!-- START HTML -->
-## Event Types
+<table class="compat" width="100%">
-- [deviceready](events.deviceready.html)
-- [pause](events.pause.html)
-- [resume](events.resume.html)
-- [backbutton](events.backbutton.html)
-- [menubutton](events.menubutton.html)
-- [searchbutton](events.searchbutton.html)
-- [startcallbutton](events.startcallbutton.html)
-- [endcallbutton](events.endcallbutton.html)
-- [volumedownbutton](events.volumedownbutton.html)
-- [volumeupbutton](events.volumeupbutton.html)
+<thead>
+ <tr>
+ <th>Supported Platforms/<br/>Events</td>
+ <th>amazon-fireos</th>
+ <th>android</th>
+ <th>blackberry10</th>
+ <th>ios</th>
+ <th>Windows Phone 8</th>
+ <th>Windows</th>
+ </tr>
+</thead>
-## Events added by
[cordova-plugin-battery-status](https://github.com/apache/cordova-plugin-battery-status/blob/master/README.md)
+<tbody>
+ <tr>
+ <th><a href="#link-deviceready">deviceready</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
-- batterycritical
-- batterylow
-- batterystatus
+ <tr>
+ <th><a href="#link-pause">pause</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
-## Events added by
[cordova-plugin-network-information](https://github.com/apache/cordova-plugin-network-information/blob/master/README.md)
+ <tr>
+ <th><a href="#link-resume">resume</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
-- online
-- offline
+ <tr>
+ <th><a href="#link-backbutton">backbutton</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
+ <tr>
+ <th><a href="#link-menubutton">menubutton</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-searchbutton">searchbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="n"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-startcallbutton">startcallbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="n"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-endcallbutton">endcallbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="n"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-volumedownbutton">volumedownbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-volumeupbutton">volumeupbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+</tbody>
+</table>
+
+<!-- END HTML -->
+
+
+**Note**: Applications typically should use `document.addEventListener` to
+attach an event listener once the [deviceready](#link-deviceready)
+event fires.
+
+## deviceready
+
+The deviceready event fires when Cordova is fully loaded. This event is
+essential to any application. It signals that Cordova's device APIs have
+loaded and are ready to access.
+
+Cordova consists of two code bases: native and JavaScript. While the
+native code loads, a custom loading image displays. However,
+JavaScript only loads once the DOM loads. This means the web app may
+potentially call a Cordova JavaScript function before the
+corresponding native code becomes available.
+
+The `deviceready` event fires once Cordova has fully loaded. Once the
+event fires, you can safely make calls to Cordova APIs. Applications
+typically attach an event listener with `document.addEventListener`
+once the HTML document's DOM has loaded.
+
+The `deviceready` event behaves somewhat differently from others. Any
+event handler registered after the `deviceready` event fires has its
+callback function called immediately.
+
+### Quick Example
+
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ function onDeviceReady() {
+ // Now safe to use device APIs
+ }
+
+### Full Example
+
+**Note**: For the sake of readability, all the other events assume that
you use the
+below html code.
+
+#### HTML File
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Device Ready Example</title>
+
+ <script type="text/javascript" charset="utf-8"
src="cordova.js"></script>
+ <script type="text/javascript" charset="utf-8"
src="example.js"></script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
+
+#### JS File
+ // example.js file
+ // Wait for device API libraries to load
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ // Now safe to use device APIs
+ }
+
+## pause
+
+The pause event fires when the native platform puts the application into
the background,
+typically when the user switches to a different application.
+
+### Quick Example
+
+ document.addEventListener("pause", onPause, false);
+
+ function onPause() {
+ // Handle the pause event
+ }
+
+### Full Example
+
+#### JS File
+ // example.js file
+ // Wait for device API libraries to load
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ document.addEventListener("pause", onPause, false);
+ }
+
+ // Handle the pause event
+ //
+ function onPause() {
+ }
+
+### iOS Quirks
+
+In the `pause` handler, any calls to the Cordova API or to native
+plugins that go through Objective-C do not work, along with any
+interactive calls, such as alerts or `console.log()`. They are only
+processed when the app resumes, on the next run loop.
+
+The iOS-specific `resign` event is available as an alternative to
+`pause`, and detects when users enable the __Lock__ button to lock the
+device with the app running in the foreground. If the app (and
+device) is enabled for multi-tasking, this is paired with a subsequent
+`pause` event, but only under iOS 5. In effect, all locked apps in iOS
+5 that have multi-tasking enabled are pushed to the background. For
+apps to remain running when locked under iOS 5, disable the app's
+multi-tasking by setting
[UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend]
+to `YES`. To run when locked on iOS 4, this setting does not matter.
+
+## resume
+
+The `resume` event fires when the native platform pulls the application
out from the background.
+
+### Quick Example
+
+ document.addEventListener("resume", onResume, false);
+
+ function onResume() {
+ // Handle the resume event
+ }
+
+### Full Example
+
+#### JS File
+ // example.js file
+ // Wait for device API libraries to load
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ document.addEventListener("resume", onResume, false);
+ }
+
+ // Handle the resume event
+ //
+ function onResume() {
+ }
+
+### iOS Quirks
+
+Any interactive functions called from a [pause](#link-pause) event handler
execute
+later when the app resumes, as signaled by the `resume` event. These
+include alerts, `console.log()`, and any calls from plugins or the
+Cordova API, which go through Objective-C.
+
+- __active__ event
+
+ The iOS-specific `active` event is available as an alternative to
+`resume`, and detects when users disable the __Lock__ button to unlock
+the device with the app running in the foreground. If the app (and
+device) is enabled for multi-tasking, this is paired with a subsequent
+`resume` event, but only under iOS 5. In effect, all locked apps in
+iOS 5 that have multi-tasking enabled are pushed to the background.
+For apps to remain running when locked under iOS 5, disable the app's
+multi-tasking by setting
[UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend]
+to `YES`. To run when locked on iOS 4, this setting does not matter.
+
+- __resume__ event
+
+ When called from a `resume` event handler, interactive functions such
+as `alert()` need to be wrapped in a `setTimeout()` call with a
+timeout value of zero, or else the app hangs. For example:
+
+ document.addEventListener("resume", onResume, false);
+ function onResume() {
+ setTimeout(function() {
+ // TODO: do your thing!
+ }, 0);
+ }
+
+### Android Quirks
+
+Refer [Android Life Cycle Guide][AndroidLifeCycleGuide] for details on
android quirks for
--- End diff --
Minor formatting/grammar edit:
Refer to the [Android Life Cycle Guide][AndroidLifeCycleGuide] for details
on Android quirks with the `resume` event.
> Make Events page a reference
> ----------------------------
>
> Key: CB-10351
> URL: https://issues.apache.org/jira/browse/CB-10351
> Project: Apache Cordova
> Issue Type: Task
> Components: Docs
> Reporter: Raghav
> Assignee: Sarangan Rajamanickam
> Labels: Docs-6.x
>
> Events page
> (https://cordova.apache.org/docs/en/latest/cordova/events/events.html) needs
> to be converted as per the new reference structure. Also add small
> descriptions to the events added by plugin-battery-status and
> plugin-network-information.
> General guidelines:
> - While giving examples, keep them short. Do not repeat for all
> plugins/platforms.
> - Remove all references to cordova plugin registry.
> - Remove Tizen references. The platform is deprecated
> (http://markmail.org/message/hryg6sjswecpgndu)
> - Keep information up to date for the platforms, CLI and plugins
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
