Within the Flash APIs is there there are many similarly named properties which provide subtly different results based on their spec and the state of the application. Width and height are such properties.
Having just read of Mike Jones’ recent article: 10 Tips When Developing For Multiple Devices, and tip #1: Check screen dimension on initialisation, it includes a couple of lines of code to get the landscape height and width of the device screen using a boolean expression to determine the longest dimension. For me this begs the question, why can’t I simply get the right values directly from the API? Especially if my app.xml properties state the app should only display landscape, full screen.
The properties examined here:
- stage.width
- stage.height
- stage.stageWidth
- stage.stageHeight
- stage.fullScreenWidth
- stage.fullScreenHeight
- stage.orientation
Although accurately described in the reference, it isn’t necessarily easy to visualise the differences in behaviour for these properties from the documentation alone. So herewith, a simple HelloWidthHeight app to trace out the values upon initialisation. Included in that app is a class implementing logic based on Mike’s as static methods. The results of debug sessions executed on my HTC Desire are detailed for comparison in the table below.
Key app.xml <initialWindow> properties used were:
- <visible>true</visible>
- <aspectRatio>landscape</aspectRatio>
- <autoOrients>false</autoOrients>
- <fullScreen>true</fullScreen>
| A | B | C | D | |
|---|---|---|---|---|
| stage.orientation | default | rotatedRight | rotatedRight | rotatedRight |
| stage.width | 0 | 0 | 0 | 0 |
| stage.height | 0 | 0 | 0 | 0 |
| stage.stageWidth | 480 | 800 | 800 | 800 |
| stage.stageHeight | 800 | 480 | 480 | 480 |
| stage.fullScreenWidth | 480 | 480 | 800 | 480 |
| stage.fullScreenHeight | 800 | 800 | 480 | 800 |
| Oriented.landscapeScreenWidth | 800 | 800 | 800 | 800 |
| Oriented.landscapeScreenHeight | 480 | 480 | 480 | 480 |
| Oriented.portraitScreenWidth | 480 | 480 | 480 | 480 |
| Oriented.portraitScreenHeight | 800 | 800 | 800 | 800 |
- Screen inactive, phone held in any orientation
- Screen active, phone lying flat on the desk
- Screen active, phone held landscape, mic to the right (this is the intended orientation for the app)
- Screen active, phone held portrait, mic to the bottom
In conclusion, unless the application is only ever launched while the screen is active (though that would be the norm), the safe way of determining an oriented width and height is to use a boolean expression along with the fullScreenWidth and fullScreenHeight properties.
UPDATE (20-July-2011): The following table runs the same code in the BlackBerry PlayBook Simulator:
| A | B | |
|---|---|---|
| stage.orientation | default | default |
| stage.width | 0 | 0 |
| stage.height | 0 | 0 |
| stage.stageWidth | 1024 | 1024 |
| stage.stageHeight | 600 | 600 |
| stage.fullScreenWidth | 1024 | 1024 |
| stage.fullScreenHeight | 600 | 600 |
| Oriented.landscapeScreenWidth | 1024 | 1024 |
| Oriented.landscapeScreenHeight | 600 | 600 |
| Oriented.portraitScreenWidth | 600 | 600 |
| Oriented.portraitScreenHeight | 1024 | 1024 |
- Simulator initially landscape
- Simulator initially portrait
Note: Behaviour is slightly different on the PlayBook simulator in that the orientation of the application is set before the initialisation code runs. Therefore unlike on the HTC Desire, fullScreenWidth and fullScreenHeight are correctly returned as the orientation of the application expects.
If anyone else cares to run the code, I’d be interested to hear how variable other devices are in their results, or if this is showing a bug when run on HTC Desire. Running AIR 2.7 here.