With the release of Titanium Mobile SDK 1.7.2, we are making some changes to orientation behavior focused mainly on Android. These changes bring the behavior more in line with how orientation works in a native app and enhance our support for tablet and 3.x (Honeycomb) devices.
In order to understand the driving force behind the changes, it is important to understand the orientation behavior on Android. There are a few key things to remember when dealing with orientation in Android:
1) Orientation values that can be requested go beyond the values that get reported back when orientation actually changes. For example: when setting orientation in a native app, you may be able to ask for reverse portrait or reverse landscape but Android itself will only report whether the orientation is portrait or landscape – not the specific type of portrait or landscape. On many devices you can make assumptions regarding the sensor degrees of the device and do a little math to determine the orientation but that brings us to the next point…
2) Orientation values do not match up to sensor degrees across all devices. For example: on a Droid 2, portrait mode (the primary mode) is when the “top” of the device is at the 0 degree position and landscape mode (secondary mode) is when the “top” of the device is at the 270 degree position. On a Xoom however, landscape mode (the primary mode) is when the “top” of the device is at the 0 degree position and portrait mode (secondary mode) is when the “top” of the device is at the 90 degree position. Note the difference in the secondary modes. Due to the hardware configuration of the device (location of the camera, etc) the position of a certain orientation mode may not be exactly where you expect it to be.
Given this understanding, its important to mentally break apart the values you use when setting orientation versus the value you get when requesting orientation. The value you get when requesting the current orientation is geared more toward the general orientation of the device (useful for knowing what resources to use). The values you use to set orientation are actually much more detailed allowing for setting the specific orientation of the device.
Titanium.UI.orientation is now deprecated and should no longer be used for setting orientation mode. Instead, it is suggested to set the orientation mode or modes on the
Titanium.UI.Window.orientationModes property since orientation in Titanium is linked to the window itself.
The following lists the orientation behavior that can be expected when setting various modes on
- Any portrait mode AND any landscape mode: this combination will set the screen orientation to be driven by the sensor and default OS behavior.
- Both portrait modes: on API level 9 (2.3.0) and above, this will set the screen orientation to be “sensor portrait” which allows the OS to shift the orientation to either of the portrait orientation modes based on what the sensor reports. If the device is older than API level 9 then this will lock the orientation to what the device considers portrait.
- Both landscape modes: same as #2, just for landscape.
- Portrait mode: locks orientation to portrait
- Landscape mode: locks orientation to landscape
- None: if you set the
Titanium.UI.Window.orientationModesarray to be empty, then this defaults back to full sensor mode (same as #1)
Kitchen Sink examples: