Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

ScreenOrientation

Methods5
Methods - Class
leftHandednormalrightHandedsetScreenOrientationEventupsideDown
Properties1
Class Properties
autoRotate
Examples3
Detect screen orientation changesChange screen orientationEnable / disable auto rotate

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

Enabling the API

In order to use this API you must include the following extension in your build.yml.

extensions: ["screenorientation"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Persistence

With the old PocketBrowser / RhoElements 1 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.

Synchronous Return:

  • Void

Method Access:

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

Sets the screen orientation to default device orientation.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ScreenOrientation.normal()
    • Ruby: Rho::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.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ScreenOrientation.rightHanded()
    • Ruby: Rho::ScreenOrientation.rightHanded()
setScreenOrientationEvent
(CallBackHandler callback)

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

Parameters

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: STRING

    Synchronous Return:

    • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.ScreenOrientation.setScreenOrientationEvent(CallBackHandler callback)
      • Ruby: Rho::ScreenOrientation.setScreenOrientationEvent(CallBackHandler callback)
    upsideDown
    ()

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

    Synchronous Return:

    • Void

    Method Access:

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

    Properties

    autoRotate
    : BOOLEAN

    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.

    Default: true

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.autoRotate

    Examples

    Detect screen orientation changes

    Detect when the device changes orientation.

    function start_detecting_orientation_changes(){
  ScreenOrientation.setScreenOrientationEvent(orientation_callback)
}

function orientation_callback(){

  Alert.show_popup("The screen changed orientation")
}
                   
                            
    def start_detecting_orientation_changes
  Rho::ScreenOrientation.setScreenOrientationEvent(url_for(:action => :orientation_callback))
end

def orientation_callback
  Alert.show_popup("The screen changed orientation")
end
    Change screen orientation

    Set the screen orientation programmatically. Particularly useful in a tablet: before capturing a signature, set the orientation to upside-down so that the interface will look right from the signer’s point of view without having to physically rotate the device.

    function capture_signature_with_attention_to_details() {
    // Set screen orientation to upside down
    Rho.ScreenOrientation.upsideDown();

    // At this point, offer the device to the user. You just saved the user the hassle of rotating the tablet
    // and there's less potential for the device to be dropped along the way
    Rho.Signature.takeFullScreen({}, signature_callback);
}

function signature_callback(params) {
    // do whatever we need to do with the signature
    ...
    // restore screen orientation to default
    Rho.ScreenOrientation.normal();
}
                   
                            
    def capture_signature_with_attention_to_details
    # Set screen orientation to upside down
    Rho::ScreenOrientation.upsideDown
    # At this point, offer the device to the user. You just saved the user the hassle of rotating the tablet
    # and there's less potential for the device to be dropped along the way
    Rho::Signature.takeFullScreen({}, url_for(:action => :signature_callback))
end

def signature_callback
    # do whatever we need to do with the signature
    ...
    # restore screen orientation to default
    Rho::ScreenOrientation.normal
end
    Enable / disable auto rotate

    Enable / disable automatic rotation of the screen according to device orientation.

    // Enable autorotate
Rho.ScreenOrientation.autoRotate=true;

// Disable autorotate
Rho.ScreenOrientation.autoRotate=false;
                   
                            
    # Enable autorotate
Rho::ScreenOrientation.autoRotate=true

# Disable autorotate
Rho::ScreenOrientation.autoRotate=false