Portrait Mode on StanbyME

For the StanbyME model, you can make your app to be displayed in portrait mode. This session guides you how you design and implement your app to support portrait mode for the StanbyME model.

In the following two cases, your app may need to change the UI of your app to fit portrait mode.

• When users run your app in portrait mode of the TV
• When users change the TV to portrait mode while the app is running.

These are the steps to follow to enable your app to support portrait mode.

1. Set properties in the appinfo.json file.
2. Check if the TV device is a StanbyMe model.
3. Check the screen orientation during app launch.
4. Change the app layout if the orientation changes.

Setting property in your app

To make your app to support portrait mode, insert the supportPortraitMode property and set the property to true in the appinfo.json file of your app. You can also set the background color and the fit mode of the splash image. For more information about the splash image, see the splashColor property and the splashFitModeOnPortrait property.

Checking StanbyME model

To distinguish whether the TV is the StanbyMe model, check the values of the webOSSystem.screenOrientation property or the webOSSystem.currentOrientation property.

• webOSSystem.screenOrientation: It returns the screen orientation of the actual TV device. The value is changed when a user changes the screen orientation of the actual device.
• webOSSystem.currentOrientation: It returns the window orientation of the web app. The value is changed when the window’s screen rotation is set by calling the webOSSystem.setWindowOrientation API.

The following table shows a comparison between webOSSystem.screenOrientation and webOSSystem.currentOrientation.

The following example shows how to determine whether the TV is a rotatable model by checking the webOSSystem.currentOrientation property.

if (webOSSystem.currentOrientation === undefined) {
  //  This device is not a rotational webOS TV
} else {
  //  This device is a rotational webOS TV
}

Checking screen orientation during app launch

The layout rotation might not be applied to your app if the screenOrientationChange event is raised before the event handler is added during your app launch. To prevent this problem, you should check the TV screen's rotation using the webOSSystem.screenOrientation property during your app launch.

The property values of the API are the same as the screenOrientationChange event.

• "landscape": 0º clockwise rotation
• "portrait": 90º clockwise rotation
• "reversed_landscape": 180º clockwise rotation
• "reversed_portrait": 270º clockwise rotation

var orientation = webOSSystem.screenOrientation;
if (orientation === 'landscape' || orientation === 'reversed_landscape') {
  // Load horizontal layout
} else if (orientation === 'portrait' || orientation === 'reversed_portrait') {
  // Load vertical layout
} else {
  // Load default layout
}

Changing app layout by screen rotation

The scenario for changing your app layout between the horizontal and vertical screen is as follows:

1. When the TV screen is rotated, the app receives orientation information using the screenOrientationChange event handler.
2. The app asks the web engine to set the app’s window orientation by calling the webOSSystem.setWindowOrientation API.
3. The web engine rotates the window and raises the window resize events.
4. When the app receives the window resize event, the app changes its layout.

The following example shows the skeleton code of how to implement the portrait mode of your app on the StanbyME model.

// Step 1. Handling the screenOrientationChange event
document.addEventListener('screenOrientationChange', function (event) {
  console.log('handleScreenOrientationChange', event.screenOrientation);
  // Step 2. Calling the webOSSystem.setWindowOrientation API
  webOSSystem.setWindowOrientation(event.screenOrientation);
});

// Step 3. Handling the window resize event
window.onresize = function () {
  console.log(
    'width x height : ' + window.innerWidth + ' x ' + window.innerHeight
  );
  // Change app layout
};

Step1. Handling the screenOrientationChange event

When the orientation of the TV has changed, the screenOrientationChange event is raised. You should add an event handler to let your app receives the following event.screenOrientation property values:

• "landscape": 0º clockwise rotation
• "portrait": 90º clockwise rotation
• "reversed_landscape": 180º clockwise rotation
• "reversed_portrait": 270º clockwise rotation

Step2. Calling the webOSSystem.setWindowOrientation API

When the event handler receives the screenOrientationChange event, you should call the webOSSystem.setWindowOrientation API to request the web engine to re-set the window's orientation.

Note that the window resize event can be raised after you call the webOSSystem.setWindowOrientation API.

Step3. Handling the window resize event

To change your app's layout depending on the orientation, you should register the resize event handler. When the resize event is raised, you should change your app's layout.

For more information about the window resize event, refer to Window: resize event.

// Handling the focus event to recall the webOSSystem.setWindowOrientation API after app switching

document.addEventListener("focus", function() {
    webOSSystem.setWindowOrientation(webOSSystem.screenOrientation);
});

Not supporting portrait mode

If you do not change the configuration, your app runs in landscape mode even if the TV device is rotated to landscape mode. That means a user will see 90 degrees rotated display as in the image.

Disabling your app in portrait mode

If you think that your app is not suitable for portrait mode, you can disable your app in portrait mode. Your app will not run in portrait mode, and the toast popup will say that your app does not support portrait mode.

Setting property in your app

To disable your app in portrait mode, insert the closeOnRotation property and set the property to true in the appinfo.json file of your app.