Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (athena.apache.org: domain of msierra@adobe.com designates
 64.18.1.234 as permitted sender)
From: Michael Sierra <msierra@adobe.com>
To: "dev@cordova.apache.org" <dev@cordova.apache.org>
CC: Michael Sierra <msierra@adobe.com>
Date: Mon, 20 May 2013 12:35:21 -0700
Subject: FW: cordova API doc queries
Thread-Topic: cordova API doc queries
Thread-Index: AQHOVY+rorxZ5dA1skKSFYVKvGb8Hg==
Message-ID: 
 <35C02676BF7FD84F92417E42E09DD8DCBCEC8F8FF0@nambx08.corp.adobe.com>
References: 
 <35C02676BF7FD84F92417E42E09DD8DCBCEC8F8FEE@nambx08.corp.adobe.com>
In-Reply-To: 
 <35C02676BF7FD84F92417E42E09DD8DCBCEC8F8FEE@nambx08.corp.adobe.com>
Accept-Language: en-US
Content-Language: en-US
acceptlanguage: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

I'm doing some work on the cordova doc, including the API ref. Based on a r=
ead-through of existing doc & no testing yet, I collected some queries that=
 Brian Leroux suggested would be appropriate for this list.

* The criteria for when online/offline events fire (internet
  connection) seem vague, especially with ubiquitous non-Wifi network
  options.  Do various devices use the same threshold criteria to fire
  the event?

* Do relevant online/offline events fire when the app starts up, or
  only when a change is detected during execution? The text for the
  offline event iOS quirk implies the former case: "During initial
  startup, the first offline event (if applicable) takes at least a
  second to fire." If it fires when the app inits, is the value of
  navigator.onLine true or false during that 1-second delay?

* When navigator.onLine =3D=3D false, is connection.type NONE by
  definition? Are there any known cases of connection type UNKNOWN
  when you're offline?

* Extraneous question: Are there plans to implement the W3C-spec'd
  "change" event for navigator.connection? It would make the feature
  more useful in conjunction with online/offline. (Too bad there's no
  spec for when your data plan is unlimited...)

* The APIs track closely to the W3C specs, but may lag. Are there
  any similar cases where there are spec'd features not implemented
  in the corresponding Cordova APIs?

* The doc for the "pause" and "retrieve" events say "native code"
  takes the app in and out of the background.  Yes, but does that mean
  it can be controlled by anything other than direct user manipulation?
  E.g., an app can't pause itself, correct?

* Extraneous question: Do developers ever use appCache manifests to
  update components passively & separately from native update options?

* Re "resume" event iOS quirks, do all calls to plugins or the Cordova
  API by definition go through Objective-C?

* The doc for the searchbutton event says: "The event fires when the
  user presses the search button on Android."  Does this mean only
  Android devices have a search button, or that it doesn't fire on
  other devices that may also have a search button?

* The same question applies to Android's menu button. Does it appear
  only on Android, or is it only supported on Android?

For several events the doc says you can "override" default button
behavior, which needs clarification:

* By default, would pressing the back button return to the home screen
  from which you launched the app?  Does a "backbutton" handler
  disable this, perhaps replaced by behavior tied to the
  browser-specific history API?

* Would "startcallbutton" & "endcallbutton" handlers actually
  interfere with your ability to start and end calls? Otherwise what
  does "override" mean in this context?

* Would a typical use case for a "searchbutton" handler be for an app
  to provide its own search UI?

* Would a typical use case for "volumedownbutton" & "volumeupbutton"
  handlers be to modify volume for playback of a particular media
  file, rather than affecting the overall device volume level?

* Please confirm: by default, these handlers "override" default button
  behavior, but with no need to call event.preventDefault().

Thanks,

--Mike Sierra