ScreenOrientation

Enterprise Browser 3.5

Overview

The ScreenOrientation Module is used to control the screen orientation / layout and register to receive an event when it changes.

Enabling the API

There are two methods of enabling the ScreenOrientation API:

  • Include all ebapi modules
  • Include only the required API modules

For either of these methods, you'll need to include files from the /Enterprise Browser/JavaScript Files/Enterprise Browser directory on the computer that you installed the Enterprise Browser.

Include all JS API modules

To include all JS APIs, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html, copy the file to the same directory as that index.html and add the following line to the HTML's HEAD section:


<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

Note: that the pathing for this file is relative to the current page.

This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.

Include only the required modules

To include single APIs, you must first include the ebapi.js in your HTML as well as the API file you want to use. For instance, to use the ScreenOrientation API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.


<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.screenorientation.js"></script>

The ebapi.js file is necessary for all single API inclusions.

Persistence

With the old PocketBrowser APIs, any events, such as screenOrientationEvent were canceled when a full navigate was performed. The original reason for this was a limitation of the IE engine on WM5 devices. When moving to the common API this was changed so that callbacks are not canceled.

Methods

leftHanded()

Sets the screen orientation to left-handed orientation. Note the webpage will not reformat in line with the new screen size automatically.

Parameters

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.ScreenOrientation.leftHanded()

normal()

Sets the screen orientation to default device orientation.

Parameters

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.ScreenOrientation.normal()

rightHanded()

Sets the screen orientation to right-handed orientation. Note the webpage will not reformat in line with the new screen size automatically.

Parameters

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.ScreenOrientation.rightHanded()

setScreenOrientationEvent()

Sets the callback to be called when a screen orientation event occurs.

Parameters

  • callback : CallBackHandler

Callback

Async Callback Returning Parameters: STRING

    Returns

    Synchronous Return:

    • Void

    Platforms

    • Android
    • Windows Mobile

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • EB.ScreenOrientation.setScreenOrientationEvent()

    upsideDown()

    Sets the screen orientation to upside down, useful if presenting the device to a customer to obtain a signature.

    Parameters

    • callback : CallBackHandler

    Returns

    Synchronous Return:

    • Void

    Platforms

    • Android
    • Windows Mobile

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • EB.ScreenOrientation.upsideDown()

    Properties

    autoRotate

    Type

    BOOLEAN

    Description

    Enables or Disables auto-rotation of the screen orientation when the device is rotated. For Windows Mobile/CE devices, support is limited to only Symbol Technologies devices with IST Sensor support.

    Params

    Default: true

    Access

    • Class: This property can only be accessed via the API class object.
      • EB.ScreenOrientation.autoRotate

    Platforms

    • Android
    • Windows Mobile

    Examples

    Manipulating the Screen Orientation

    In this example you'll see how to manipulate the screen orientation and how to receive events when the orientation changes. This example assumes that the ebapi-modules.js file resides in the same folder as the HTML file invoking it.

    
    <head>
        <script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>
    
        <title>ScreenOrientation API Test</title>
    
        <script>
            function orientationEventCallback(params){
                display.innerHTML = "Orientation: " + params;
            }
    
            function changeOrientation(direction){
                switch(direction){
                    case "left":
                        EB.ScreenOrientation.leftHanded();
                        break;
                    case "right":
                        EB.ScreenOrientation.rightHanded();
                        break;
                    case "normal":
                        EB.ScreenOrientation.normal();
                        break;
                    case "upsideDown":
                        EB.ScreenOrientation.upsideDown();
                        break;
                    default:
                        alert('Incorrect Orientation!!');
                }
            }
    
            function toggleAutoRotate(){
                if(EB.ScreenOrientation.autoRotate){
                    EB.ScreenOrientation.autoRotate = false;
                    autoRotate.innerHTML = 'Auto Rotate: Disabled';
                }
                else{
                    EB.ScreenOrientation.autoRotate = true;
                    autoRotate.innerHTML = 'Auto Rotate: Enabled';
                }
            }
    
            EB.ScreenOrientation.setScreenOrientationEvent(orientationEventCallback);
        </script>
    </head>
    
    <body>
        <h1>ScreenOrientation API Test</h1>
        <div id="display">
            Orientation:
        </div>
        <div id="autoRotate">
            Auto Rotate: Enabled
        </div>
        <div>
            <button onclick="toggleAutoRotate()">Toggle Auto Rotate</button>
            </br></br>
            <button onclick="changeOrientation('normal')">Upright Portrait</button></br>
            <button onclick="changeOrientation('right')">Counter-Clockwise</button>
            <button onclick="changeOrientation('left')">Clockwise</button></br>
            <button onclick="changeOrientation('upsideDown')">Upside-Down</button></br>
        </div>
    </body>