Introduction

Dealing with screen orientation basically consists in arranging the current on-screen display - and the associated feature set and interactions - according to the current screen orientation. One typical use-case for mobile tv applications consists in having an instrumented display (channels list, program information...) with delimited area for the video in portrait mode vs a fullscreen video in landscape mode.

There are basically 2 types of actions that can induce a Rich Media Application orientation change:

• hardware / device driven orientation changes, i.e. the device is equipped with a gyro or any mechanicalk trigger (keyboard deployment...) and an inner interpretation of the information delivered by this equipment; the display is supposed to automatically change according to the current orientation given to the device by the end-user
• software / application driven orientation changes, i.e. changing the display orientation is an operation availed in the application itself; such operation to "force" screen orientation may be offered to the end-user or automatically triggered by the application in a given context

One will have to figure out what is the appropriate display for a given Rich Media Application:

• in all possible orientations, i.e. 2 in portrait and 2 in landscape,
• when the application is launched (initial display) and during runtime,
• if the expected screen orientation changes are supposed to be "auto" (i.e. driven by the hardware / device) or "manual" (i.e. driven by the application / software).

Such decision shall be performed at early stage in the Rich Media Application realization lifecyle, as it will affect its design and ultimately the end-user experience.

Generalities

Initial screen orientation

First thing one will have to define is what is supposed to be the initial orientation display and the default screen orientation detection when the application is launched:

• on equipped devices (i.e. devices with multiple screen orientations driven by hardware such as a gyro, the keyboard expansion...), it is possible to:
  • specify the default orientation, i.e. specify which screen orientation (among the 4 possibilities) to apply to the application display at application launch, whatever the device orientation
  • specify the initial screen orientation orientation as being in "auto" or "manual" mode; if set to "auto", when the application is launched it will react to the current device orientation (if the device is oriented in portrait, the application will be displayed in portrait / if the device is oriented in landscape the application will be displayed in landscape) and orientation changes
• on other devices supporting multiple screen orientations display, it is only applicable to set the initial orientation ("manual" is the only applicable mode), i.e. specify which screen orientation (among the 4 possibilities) to apply to the application display at application launch

Such configuration is part of the Rich Media Application customization:

1. Launch Devices > Rich Media Client customization
2. Select the target platform(s) for the Rich Media Application
3. Select the Advanced settings tab
4. Specify the initial Screen orientation
5. Specify the Switching mode: "Auto" or "Manual"

The specified customization is used when generating the client packages for the target devices in order to configure the generated application appropriately.

Runtime screen orientation

Once one has defined how the Rich Media Application will react to screen orientation changes and has specified the expected behaviour at application launch, the developer will have to specify how to rearrange the display and offered interactions according when screen orientation will change will the Rich Media Application is running.

Streamezzo framework offers the following facilities:

• "auto" mode: detect the screen orientation changes, identify what is the new current screen orientation and adapt the application display accordingly
• "manual" mode: specify the new current screen orientation and adapt the application according accordingly, once the change is effective

At anytime it will be possible to enable / disable the "auto" mode, i.e. if part of the application only supports a single orientation.

In both cases this requires very few lines of code to be performed, as detailed in the next sections, considering the "auto" and "manual" mode separately.

The Rich Media Application display should be designed as being drawn in a square:

• which dimensions are max(screen width, screen height) * max(screen width, screen height)
• which only part of it is displayed when the current orientation is portrait vs landscape, as stated in the figure below

Platform support

Plattform Feature	Android	BlackBerry	BREW	iPhone	J2ME	NS602  FP2/3	NS603	NS605	WM2005 PPC	WM2005 Smart Phone
Screen orientation change	*			*			*	*	*	*
Auto rotation	*	N/A	N/A	*	N/A	N/A	*	*	*	*
Auto rotation runtime activation / deactivation	*	N/A	N/A		N/A	N/A	*	*	*	*

* Depending on the device, feature support may be limited or even unavailable.

Auto screen orientation

Device drives the screen orientation changes, application adapts to those changes.

Initial screen orientation

Runtime screen orientation

The following instructions have to be included within the code:

• AnimateActivate with 2 ActivateKey
  • duration=0 is triggered when screen orientation switches to portrait
  • duration=1 is triggered when screen orientation switches to landscape
• Replace configures the AnimateActivate as reacting to screen orientation (GSO)
• Finally each of the ActivateKey specified above are supposed to activate the appropriate nodes, i.e. the ones supposed to be active when oriented in portrait vs landscape respectively

The code sample (Workbench Developer project available for download at the bottom of this page) below illustrates this implementation:

" colorBits="8" lengthBits="16" resolution="2" idBits="16" scaleBits="15" encodingType="0"/>

The following configuration is applicable to emulate this code sample:

Finally for devices supporting the "auto" mode, it is possible at anytime during the Rich Media Application usage session to disable the "auto" mode, i.e. if some parts of the application do not support multiple screen orientations. This can be achieved thanks to the commannd setScreenOrientation, setting the auto parameter to "OFF" (respectively to "ON" to reactivate the "auto" mode).

In such case the application will be behave in "manual" mode, which implementation is detailed in the next section.

Manual screen orientation

Application drives the screen orientation changes and adapts to those changes.

Initial screen orientation

Runtime screen orientation

The following instructions have to be included within the code:

• Command setScreenOrientation is called when the screen orientation must be changed to a a given orientation (specified in parameter)
• Command parameter onSuccess enables starting a target node when the screen orientation change is effective
• Finally the target startable node specified above is supposed to act on the appropriate nodes, i.e. configure them according to portrait vs landscape respectively

The expected orientation can be specified either with an absolute value (i.e. a defined screen orientation) or a relative value (i.e. depends on the previous screen orientation):

• M0: main orientation of device. Can be portrait or landscape depending on the device general shape. If accelerometer is on standing device, this orientation corresponds to a (0.0 1.0 0.0) triplet got from it.

• M1: M0 orientation with one additional 90° anti-clockwise rotation. If accelerometer is on standing device, this orientation corresponds to a (-1.0 0.0 0.0) triplet got from it.

• M2: M0 orientation with one additional 180° rotation. If accelerometer is on standing device, this orientation corresponds to a (0.0 0.0 -1.0) triplet got from it.

• M3: M0 orientation with one additional 90° clockwise rotation. If accelerometer is on standing device, this orientation corresponds to a (1.0 0.0 0.0) triplet got from it.

• P0: main portrait mode of device. This is M0 for a portrait device or the orientation of a 90° anti-clockwise rotated landscape device – right handed rotation.

• L0: main landscape mode of device. This is M0 of a landscape device or the orientation of a 90° anti-clockwise rotated portrait device – right handed rotation.

• P1: secondary portrait mode of device This is the 180° orientation of a portrait device or the orientation of a 90° clockwise rotated landscape device – left handed rotation.

• L1: secondary landscape mode of device. This is the 180° orientation of a landscape device or the orientation of a 90° clockwise rotated portrait device – left handed rotation.

The code sample (Workbench Developer project available for download at the bottom of this page) below illustrates this implementation:

<%@ page import="java.lang.Math" %> <% int screenWidth = userAgent.getScreenWidth(); int screenHeight = userAgent.getScreenHeight(); // Important: content is designed as a square box which elements will be displayed or not in either portrait or landscape orientation int screenDimension = Math.max(screenWidth, screenHeight); %>

"/> "> "> "> ">

The following configuration is applicable to emulate this code sample:

Screen orientation emulation

Emulating the Rich Media Application will enable to check the Rich Media Application behaviour in either in "auto" or "manual" mode.

Initial screen orientation

In order to configure the emulator in accordance with the Rich Media Application customization, the initial screen orientation can be specified (i.e. initial screen orientation and switching mode).

• Launch emulation (Service > Emulate Service)
• Select Options tab
• Enable screen orientation
• Configure screen orientation

Runtime screen orientation

When emulating for each mode:

• in "auto" mode, the orientation buttons displayed at below the Device emulator ( and ) enable to simulate a hardware / device driven screen orientation change
• in "manual" mode, the interactions or the context in which the Rich Media Application is supposed to change the screen orientation will induce the expected adaptation of the display