The ScreenOrientation Module is used to control the screen orientation/layout and register to receive an event when it changes.
| screenOrientation (Module) <META> Syntax |
|---|
<META HTTP-Equiv="ScreenOrientation" content="[orientation]"> |
<META HTTP-Equiv="ScreenOrientation" content="ScreenOrientationEvent:url('[jsFunction | url]')"> |
| ScreenOrientation JavaScript Object Syntax: |
|---|
| By default the JavaScript Object 'screenOrientation' will exist on the current page and can be used to interact directly with the screenOrientation. |
| To Invoke screenOrientation methods via JavaScript use the following syntax: screenorientation.method(); e.g. screenOrientation.normal(); |
| To Set screenOrientation parameters via JavaScript use the following syntax: screenorientation.parameter = 'value'; remembering to enclose your value in quotes where appropriate. e.g. screenOrientation.autoRotate = 'value'; |
| To Set screenOrientation return events via JavaScript use the following syntax: screenorientation.event = JavaScript Function; e.g. screenOrientation.screenOrientationEvent = 'doFunction(%json)'; For more details on the event syntax and parameters see the Retrieval Events page. |
| To set multiple EMML parameters / events on a single line use the following syntax: screenorientation.setEMML("[Your EMML Tags]"); e.g. screenOrientation.setEMML("autoRotate:value;screenOrientationEvent:url('JavaScript:doFunction(%json)');normal"); |
| ScreenOrientation Ruby Object Syntax: |
|---|
| By default the Ruby Object 'ScreenOrientation' will exist on the current page and can be used to interact directly with the ScreenOrientation. All Methods, Parameters and Events are the same as JavaScript, however, notice 'ScreenOrientation' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()' |
| To Invoke ScreenOrientation methods via Ruby use the following syntax: ScreenOrientation.method() e.g. ScreenOrientation.normal |
| To Set ScreenOrientation parameters via Ruby use the following syntax: ScreenOrientation.parameter = 'value' remembering to enclose your value in quotes where appropriate. e.g. ScreenOrientation.autoRotate = 'value' |
|
To Set ScreenOrientation return events via Ruby use the following syntax: ScreenOrientation.event = url_for(:action => :event_callback)
e.g. ScreenOrientation.screenOrientationEvent = url_for(:action => :screenorientation_event_callback)
For more details on the event syntax and parameters see the Retrieval Events page.
To access the event parameters in a Ruby callback function, you reference the @params object within the callback function. This object is simply a ruby hash {"parameter1 name" => "parameter1 value", "parameter2 name" => "parameter2 value", ...} |
Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.
| Name | Description | Default Value |
|---|---|---|
| normal | Sets the screen orientation to portrait | Device Dependant |
| rightHanded | Sets the screen orientation to righthanded (landscape). Note the webpage will not reformat in line with the new screen size automatically. | Device Dependant |
| leftHanded | Sets the screen orientation to lefthanded (landscape). Note the webpage will not reformat in line with the new screen size automatically. | Device Dependant |
| upsideDown | Sets the screen orientation to upside down, useful if presenting the device to a customer to obtain a signature. | Device Dependant |
Items listed in this section indicate parameters, or attributes which can be set.
| Name | Possible Values | Description | Default Value |
|---|---|---|---|
| autoRotate:[Value] | 'Enabled' or 'Disabled' | Enables or Disables autorotation of the screen orientation when the device is rotated | Defined in Configuration File |
Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.
The screen orientation event is sent when the current RhoElements application changes the orientation of the screen. For devices with an inbuilt accelerometer this event will also be sent when the user physically rotates the device to a new orientation.
| ID | Name | Description |
|---|---|---|
| 1 | orientation | Either 'normal', 'rightHanded', 'leftHanded' or 'upsideDown' |
When multiple RhoElememts applications are running the following considerations should be made: The screen orientation settings are application specific. Switching to another application which uses the ScreenOrientation module will cause the screen to be rotated automatically if necessary
When the screen orientation changes, either using the ScreenOrientation tag or by rotating a device with hardware support, the command areas will automatically move and resize to fit the new layout. However the buttons themselves are not moved and in some cases this may result in them being off the screen or not in the expected position. If so they must be moved manually by detecting the ScreenOrientationEvent.
In all devices apart from the Enterprise Tablet, orientation changes will persist if RhoElements is closed or the device is warm booted.
By default the Screen Orientation module will assume the “Normal” orientation of your device is portrait mode. Devices which default to landscape mode (e.g. VC model devices) may need to be set to “leftHanded” in order to achieve an ‘out of the box’ orientation.
| RhoElements Version | 1.0.0 or above |
|---|---|
| Supported Devices | All supported devices. autoRotate is only supported in devices that have IST. |
| Minimum Requirements | A device with a screen. |
| Persistence | Partially Persistent - Changes to this module will persist when navigating to a new page with the exception of ScreenOrientationEvent |
The following example orientates the screen to righthanded in landscape mode:
<META HTTP-Equiv="ScreenOrientation" Content="RightHanded">