Mailing-List: contact callback-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: callback-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of purplecabbage@gmail.com
 designates 209.85.220.175 as permitted sender)
MIME-Version: 1.0
Date: Mon, 24 Oct 2011 12:22:36 -0700
Message-ID: 
 <CAKP6k2uTrUz4cMPnySom-QxHXJGqq3WR58z8Fx6tu07ZkQryNg@mail.gmail.com>
Subject: [PROPOSAL] Orientation Interface
From: Jesse <purplecabbage@gmail.com>
To: callback-dev@incubator.apache.org
Content-Type: multipart/alternative; boundary=20cf3079b74e77d9a004b0105880

--20cf3079b74e77d9a004b0105880
Content-Type: text/plain; charset=ISO-8859-1

This proposal is intended to be a discussion, so if you have strong feelings
about anything here, or any recommendations or corrections, this thread
should be the outlet for that.  Upon reaching some general consensus, and
having the concept sit with everyone for a bit, we will put it to a vote.

The proposal (in brief):
Add a JavaScript interface to allow developers to specify at runtime what
orientations they allow.

A simple use-case :

- an app with 2 views, managed by manipulating the DOM, and showing/hiding
elements

View 1 is a list of flickr images with a thumbnail, title, date + author
info.
This view should not re-orient and should always be displayed in portrait.
Selecting an item shows View2.

View 2 is an image view of the selected image
User should be allowed to freely re-orient the device to their pleasing, for
viewing the picture.
Clicking a close button returns the user to View1


The current implementation:

- all major CallBack devices support orientation, but the method that you
use to specify which orientation your app will allow are different.
- supported orientations are uniformly mapped on devices to 0,-90,90,180
- orientations are a build time setting, and there is no way to change what
you support at runtime.


iOS
----

 - plist specifies supported orientations

Android
----

 - manifest.xml specifies
<application>
    <activity android:configChanges="orientation|keyboardHidden"> ...
</application>

BB WebWorks
----

<autoOrients>false</autoOrients>
<aspectRatio>landscape</aspectRatio>

WP7
----

<phone:PhoneApplicationPage
  SupportedOrientations="Portrait" Orientation="Portrait"
  ... ></phone:PhoneApplicationPage>

The proposal (in detail):

1. All devices should support a runtime getter/setter on the static JS
PhoneGap object.
2. The 'property' should be called supportedOrientations and should be an
array of integer values.
ex.
    // allow the device to orient to Portrait or PortraitUpsidedown
    PhoneGap.supportedOrientations = [0,180];

3. Orientation events should NOT be sent when the device is moved to an
unsupported orientation.
4. supportedOrientations should be considered to be in order of preference.
5. setting supportedOrientations to a value that would preclude the current
physical device orientation should trigger an immediate orientation change
and subsequent change event.
ex.
    // Device is currently in landscape left
    PhoneGap.supportedOrientations = [0,180];
    // result : Native view reorients to Portrait and triggers orientation
change event.


Cheers,
  Jesse

--20cf3079b74e77d9a004b0105880--