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>