OrientationSupport

Since: BlackBerry 10.0.0

#include <bb/cascades/OrientationSupport>

Provides support for display and UI orientation changes.

Using this class you can specify the supported display orientations, force display orientation changes, make changes in response to device orientation changes, and track a device's display direction.

OrientationSupport includes the following properties:

  • supportedDisplayOrientation: Specifies the display orientations that the application supports or forces a particular orientation (if the current orientation doesn't match the specified orientation). This property restricts the values that orientation and displayDirection properties can have. The property is initialized based on the Orientation property set in the application manifest (see below for details). Note: This property is read only for applications launched as cards, and property value is initialized to SupportedDisplayOrientation::All since parent application controls the orientation.

  • orientation: A read-only property that specifies the current orientation of the UI: either UIOrientation::Portrait or UIOrientation::Landscape. The application can listen to changes to this property in order to respond to orientation changes, if specific actions must be performed when the orientation changes (for example, changing the contents of the scene when the orientation changes from landscape to portrait). The application has the opportunity to perform actions both before and after the orientation change occurs.

  • displayDirection: A read-only property that represents the current DisplayDirection. The display direction is the angle between device's natural orientation (with BlackBerry logo pointing up) and the device's current direction. The natural display direction is represented by DisplayDirection::North (0 degrees). The value of this property may change even if value of orientation doesn't. For example if the device is rotated 180 degrees, in this case orientation doesn't not change but direction does, to reflect where the top of the device is pointing.

Setting the orientation

You can set the orientation properties for an app on the Application tab in the bar-descriptor.xml file. The value of the Orientation property is used to initialize the supportedDisplayOrientation property when the app starts. This value defines the initial orientation and direction the application will be started in, as well as whether the application reorients itself as the user physically rotates the device.

Applications that are intended to respond to a physical rotation must ensure that they have the correct value for the Orientation property in the bar-descriptor.xml file for the app.

Portrait and landscape

If the application is designed to reorient for both UIOrientation::Portrait and UIOrientation::Landscape, the value should be set to "Auto-orient". Using this setting, the application will be initialized to match the current device orientation when it's started, and will continue to follow the device orientation as user rotates the device. The supportedDisplayOrientation property will be initialized to SupportedDisplayOrientation::All on application start up.

Portrait only

If the application is designed to support only UIOrientation::Portrait, the value should be set to "Portrait". This setting is often used in applications that feature long, vertical lists. Using this setting, the application will be initialized in the UIOrientation::Portrait orientation and will only follow device rotations if they correspond to the UIOrientation::Portrait orientation. The supportedDisplayOrientation property will be initialized to SupportedDisplayOrientation::DisplayPortrait on application start up.

Landscape only

If the application is designed to support only UIOrientation::Landscape, the value should be set to "Landscape". This setting is often used in games that require a wide screen. Using this setting, the application will be initialized in the UIOrientation::Landscape orientation and will only follow device rotations if they correspond to the UIOrientation::Landscape orientation. The supportedDisplayOrientation property will be initialized to SupportedDisplayOrientation::DisplayLandscape on application start up.

Default

If the application is designed to only support the natural device orientation (for example, portrait for a phone or landscape for a tablet) the value should be left as "Default". Using the default setting means that the application may start in different orientations on different devices. The supportedDisplayOrientation property will be initialized to the value corresponding to the native display orientation for the device (either SupportedDisplayOrientation::DisplayPortrait or SupportedDisplayOrientation::DisplayLandscape) on application start up.

Programmatically setting the orientation

Irrespective of setting the Orientation in the application's bar-descriptor, applications can programmatically request a specific orientation (SupportedDisplayOrientation::DisplayPortrait, SupportedDisplayOrientation::DisplayLandscape or SupportedDisplayOrientation::DeviceNorth), or direction (DisplayDirection::East, DisplayDirection::West, DisplayDirection::North or DisplayDirection::South), or lock the current orientation (SuportedDisplayOrientation::CurrentLocked).

Note:

Because of a current platform limitation, if the Orientation value in the bar-descriptor is set to anything other than "Auto-orient", programmatically setting the supportedDisplayOrientation to SupportedDisplayOrientation::All will result in the device only responding to rotations that don't result in a change from portrait to landscape, or vice versa. In these cases, the application is only notified of 180 degree rotations. If the application needs to respond to all device rotations, make sure to set the Orientation property to "Auto-orient", and if required, restrict the rotations programmatically using the supportedDisplayOrientation property.

Orientation handling

When the orientation of the device (or the supportedDisplayOrientation property) changes, there are a series of property changes and emitted signals that occur. In order to create the best user experience, it's important to understand these changes so that you can respond to them promptly and appropriately.

  • When the supportedDisplayOrientation property changes, the supportedDisplayOrientationChanged signal is emitted (if changed by the application). This step only occurs when the application changes the supportedDisplayOrientation property. This signal is not emitted if the orientation changes in response to the user physically rotating the device.

  • When the displayDirection property is about to change in response to rotation, the displayDirectionAboutToChange() signal is emitted. This signal is emitted even if it is a 180 degree rotation (no orientation change). The signal is emitted before the actual UI rotation takes place, so the application has a chance to update the UI before the rotation begins. This signal is also the last chance the application has to opt out of an orientation change by setting the supportedDisplayOrientation property to a value that's incompatible with the upcoming orientation change (for example, SupportedDisplayOrientation::CurrentLocked).

  • When the displayDirection property changes, the displayDirectionChanged signal is emitted. At this moment, the orientation change is imminent. From this point on, updates to the scene will be visible by the user only after the rotation occurs.

  • When an orientation change is about to happen (in other words, a rotation that is not 180 degrees), the orientationAboutToChange signal is emitted. At this point, the application can update the UI to fit the new orientation. After this signal is handled, the actual visual rotation occurs. At the end of the rotation effect, the new scene that is set during this signal is shown. Most applications should listen for this signal, as it's usually the best opportunity to set up the scene for the new orientation.

  • After an orientation change occurs (not a 180 degree rotation), the orientation property changes, and the orientationChanged signal is emitted. At this point, the application can make additional (usually more significant, or time consuming) changes to the scene in the new orientation.

  • At the end of a rotation or orientation change, the rotationCompleted() signal is emitted. It is the last signal emitted after any rotation occurs (meaning either direction and/or orientation has changed). Applications can use this signal to perform activities that need to happen after either the direction or the orientation change has completed.

Orientation handling for square displays

If the width and height of the device's display are equal (i.e. the display is square) the relationship between the supportedDisplayOrientation and orientation behaves as follows.

Orientation handling with Cards

For invocation cards that are invoked by an application, the supportedDisplayOrientation property is read-only and automatically defaults to SupportedDisplayOrientation::All. This is because the parent application is always in charge of how orientation changes are handled. Card applications must still be ready to respond to orientation changes though. All orientation-related signals will be fired just like they are for non-Card applications.

Examples

Warning!

OrientationSupport::instance() must be handled on the application thread or a runtime error will occur.

C++

The following sample demonstrates how to initiate and respond to orientation changes from C++. The code below assumes that OrientationTest has clicked(), onOrientationAboutToChange(), and onOrientationChanged() slots.

This example also assumes that application has the Orientation property set to "Auto-orient" on the Application tab of the bar-descriptor.xml file.

OrientationTest()
{
    Button *button = Button::create().text("Toggle Orientation");
    QObject::connect(button, SIGNAL(clicked()), this, SLOT(clicked()));

    m_labelUI = Label::create();

    QObject::connect(
        OrientationSupport::instance(), 
        SIGNAL(displayDirectionAboutToChange(bb::cascades::DisplayDirection::Type,
                                             bb::cascades::UIOrientation::Type)),
        this, 
        SLOT(onDisplayDirectionAboutToChange(bb::cascades::DisplayDirection::Type,
                                             bb::cascades::UIOrientation::Type)));

    QObject::connect(
        OrientationSupport::instance(), 
        SIGNAL(orientationAboutToChange(bb::cascades::UIOrientation::Type)),
        this, 
        SLOT(onOrientationAboutToChange(bb::cascades::UIOrientation::Type)));

    // ... add controls to a container, set scene etc
}

void OrientationTest::clicked()
{
    OrientationSupport *support = OrientationSupport::instance();
    if (support->orientation() == UIOrientation::Portrait) {
        support->setSupportedDisplayOrientation(
                SupportedDisplayOrientation::DisplayLandscape);
    } else {
        support->setSupportedDisplayOrientation(
                SupportedDisplayOrientation::DisplayPortrait);
    }
}

void OrientationTest::onDisplayDirectionAboutToChange(
        DisplayDirection::Type direction,
        UIOrientation::Type orientation)
{
    // The label will have the text during orientation transition effect.
    m_labelUI->setText("Rotating, Weee!");
}

void OrientationTest::onOrientationAboutToChange(UIOrientation::Type orientation)
{
    // The label will have this text once the orientation transition is complete.
    m_labelUI->setText(orientation == UIOrientation::Landscape ?
        "Orientation: Landscape!" : "Orientation: Portrait!");
}

QML

Here's how to control and respond to orientation changes in QML. This example assumes that the application has the Orientation property set to "Auto-orient" in the Application tab of the bar-descriptor.xml file.

Container {
    Button {
        text: "Change Orientation"
        onClicked: {
            if (OrientationSupport.orientation == UIOrientation.Portrait) {
                OrientationSupport.supportedDisplayOrientation =
                    SupportedDisplayOrientation.DisplayLandscape;
            } else {
                OrientationSupport.supportedDisplayOrientation =
                    SupportedDisplayOrientation.DisplayPortrait;
            }
        }
    }
    Label {
        id: label
        text: "Current UI Orientation: " + (handler.orientation ==
                UIOrientation.Landscape ? "Landscape" : "Portrait")
    }
    attachedObjects: [
        OrientationHandler {
            id: handler
            onDisplayDirectionAboutToChange: {
                // Set UI to be shown during rotation effect.
                label.text = "Rotating, Weeee!"
            }
            onOrientationAboutToChange: {
                // Setup the scene for the new orientation.
                if (orientation == UIOrientation.Portrait) {
                    // Make some UI changes related to portrait.
                } else if (orientation == UIOrientation.Landscape) {
                    // Make some UI changes related to landscape.
                }
                if (displayDirection == DisplayDirection.North) {
                    // Do something specific to this device display direction.
                }
            }
            onOrientationChanged: {
                // Any additional changes to be performed after the orientation
                // change has occured.
            }
            onDisplayDirectionChanged: {
                // Can perform actions based on the direction of the display.
            }
            onRotationCompleted: {
                // Can perform actions after either direction or orientation
                // change has been completed.
                label.text =
                    "Current UI Orientation: " + (handler.orientation ==
                         UIOrientation.Landscape ? "Landscape" : "Portrait")
            }
        }        
    ]
}


Overview

QML properties

displayDirection: bb::cascades::DisplayDirection::Type [read-only]
orientation: bb::cascades::UIOrientation::Type [read-only]
supportedDisplayOrientation: bb::cascades::SupportedDisplayOrientation::Type

Public Functions Index

bb::cascades::DisplayDirection::TypedisplayDirection () const
bb::cascades::UIOrientation::Typeorientation () const
boolrequestDisplayDirection (bb::cascades::DisplayDirection::Type displayDirection)
Q_SLOT voidresetSupportedDisplayOrientation ()
voidsetSupportedDisplayOrientation (bb::cascades::SupportedDisplayOrientation::Type displayOrientation)
bb::cascades::SupportedDisplayOrientation::TypesupportedDisplayOrientation () const

Static Public Functions Index

Protected Functions Index

Q_INVOKABLE boolrequestDisplayDirection (int displayDirection)

Signals Index

voiddisplayDirectionAboutToChange (bb::cascades::DisplayDirection::Type displayDirection, bb::cascades::UIOrientation::Type orientation)
voiddisplayDirectionChanged (bb::cascades::DisplayDirection::Type displayDirection)
voidorientationAboutToChange (bb::cascades::UIOrientation::Type orientation)
voidorientationChanged (bb::cascades::UIOrientation::Type orientation)
voidrotationCompleted ()
voidsupportedDisplayOrientationChanged (bb::cascades::SupportedDisplayOrientation::Type displayOrientation)

Properties

bb::cascades::DisplayDirection::Type displayDirection[read-only]

The direction of the display as indicated by the direction that the top of the device display is pointing.

This is a read-only property which reflects the current display direction. Its value depends on current device direction and the value of the supportedDisplayOrientation property. The direction will only reflect supported display orientations.

This property is useful if application needs to know the exact direction the display is pointing to as opposed to just whether it is in landscape or portrait orientation.

The value of this property changes before the application receives the orientationAboutToChange() signal so the new value will be returned if this property is read when the orientationAboutToChange() signal is handled.

A displayDirectionAboutToChange() signal is emitted before this property changes. When the orientation changes, it emits the displayDirectionChanged() signal.

The default value depends on the device's physical display direction and the value of the supportedDisplayOrientation property.

Since:

BlackBerry 10.0.0

bb::cascades::UIOrientation::Type orientation[read-only]

The orientation of the user interface.

This is a read-only property which reflects current display orientation. Its value depends on the current device direction and the value of the supportedDisplayOrientation property.

When this property changes, the orientationAboutToChange() and orientationChanged() signals are emitted. When orientationAboutToChange() is emitted, the app can update the UI for the new orientation. When orientationChanged() is emitted, the application can update the UI again if needed (in case the previous UI change was intermediate).

The default value depends on devices' physical display orientation and the value of supportedDisplayOrientation property.

Since:

BlackBerry 10.0.0

bb::cascades::SupportedDisplayOrientation::Type supportedDisplayOrientation

Display orientations supported by the application.

The application can use this property to declare which display orientation it supports, as well as control the current orientation.

If the value of this property doesn't match the current orientation, the orientation will be changed to reflect the supported display orientation.

If the current supported display orientation doesn't conflict with UI orientation (like if device was rotated from one landscape orientation to another landscape orientation, 180 degrees) the orientation property will not be changed.

Under certain conditions (such as orientation change is already in progress or if application is not active), the setting of the property may fail in which case the property will remain unchanged and a warning will be logged.

The initialized orientation is based on the Orientation value set in the application's bar-descriptor.xml file, unless the application is launched as a Card.

Note:

For applications launched as cards this property is read only, and the property value defaults to SupportedDisplayOrientation::All since the parent application controls the orientation.

Since:

BlackBerry 10.0.0

Public Functions

bb::cascades::DisplayDirection::Type displayDirection ()

Returns the current value of displayDirection property.

Return:

The current display direction.

Since:

BlackBerry 10.0.0

bb::cascades::UIOrientation::Type orientation ()

Returns the current value of the orientation property.

Return:

The current UI orientation.

Since:

BlackBerry 10.0.0

bool requestDisplayDirection (

Requests a display direction change to the specified displayDirection.

The display direction change will only occur if the specified displayDirection does not conflict with the current supportedDisplayOrientation.

In case the request succeeded, the method will return true and the display direction and orientation change (the latter only if direction change is not 180 degrees) sequence will be initiated.

If the request failed, the method will return false and an error message will be printed to the log. It may fail if the direction is not supported on the device, if the display direction change was attempted during an orientation change sequence, if the application is a Card, or if application is not active.

Make sure to check the return result of the method to ensure the request succeeded.

This method is invokable from QML.

This example assumes that application has the Orientation property set to "Auto-orient" in the Application tab of the bar-descriptor.xml file.

import bb.cascades 1.0

Page {
    Container {
        Button {
            text: "Rotate To Top"
            onClicked: {
                OrientationSupport.requestDisplayDirection(DisplayDirection.North);
            }
        }
        Button {
            text: "Rotate To Left"
            onClicked: {
                OrientationSupport.requestDisplayDirection(DisplayDirection.West);
            }
        }
        Button {
            text: "Rotate To Right"
            onClicked: {
                OrientationSupport.requestDisplayDirection(DisplayDirection.East);
            }
        }
    }
}
Return:

true if request succeeded, and false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT void resetSupportedDisplayOrientation ()

Sets the supported display orientation to the default value specified in applications' bar-descriptor.xml file.

Since:

BlackBerry 10.0.0

void setSupportedDisplayOrientation (

Sets the new supported display orientation.

If current UI orientation doesn't match the new display orientaiton, orientation will be changed to satisfy the new supported display orientation.

Under certain conditions (such as the orientation change is already in progress, or the application is not active), the setting of this property may fail, in which case, the property will remain unchanged and a warning will be logged.

Note:

Since the supportedDisplayOrientation property is read-only for applications launched as Cards, calling this method for such applications has no effect and a warning will be logged.

Parameters
displayOrientation

new supported display orientation.

Since:

BlackBerry 10.0.0

bb::cascades::SupportedDisplayOrientation::Type supportedDisplayOrientation ()

Returns the current value of supportedDisplayOrientation property.

Return:

Returns currently set supported orientation.

Since:

BlackBerry 10.0.0

Static Public Functions

bb::cascades::OrientationSupport * instance ()

Returns an instance of OrientationSupport associated with this application.

The returned instance is owned by the application and ownership is not transferred to the caller.

Warning!

This method must be called on the application thread or a runtime error will occur.

Return:

The OrientationSupport instance.

Since:

BlackBerry 10.0.0

Protected Functions

Q_INVOKABLE bool requestDisplayDirection (
  • intdisplayDirection,
  • )

Requests display direction change to the specified displayDirection.

The display direction change will only occur if specified displayDirection does not conflict with current supportedDisplayOrientation.

In case the request succeeded the method will return true and the display direction and orientation change (the latter only if direction change is not 180 degrees) sequence will be initiated.

If the request failed method will return false and an error message will be printed to the log. It may fail if the direction is not supported on the device, if display direction was attempted to be changed during orientation change sequence, if the application is a Card or if application is not active. In case the request fails a diagnostic warning will be printed to the log.

Make sure to check the return result of the method to ensure the request succeeded.

This method is invokable from QML.

This example assumes that application has Orientation property set to "Auto-orient" in Application tab of the manifest editor.

import bb.cascades 1.0

Page {
    Container {
        Button {
            text: "Rotate To Top"
            onClicked: {
                OrientationSupport.requestDisplayDirection(DisplayDirection.North);
            }
        }
        Button {
            text: "Rotate To Left"
            onClicked: {
                OrientationSupport.requestDisplayDirection(DisplayDirection.West);
            }
        }
        Button {
            text: "Rotate To Right"
            onClicked: {
                OrientationSupport.requestDisplayDirection(DisplayDirection.East);
            }
        }
    }
}
Return:

true if request succeeded, false otherwise.

Since:

BlackBerry 10.1.0

Signals

void displayDirectionAboutToChange (

Emitted when display direction is about to change in response to a device rotation or a change in the supported device orientation.

The application can use this signal to perform activities before the rotation occurs or to prevent the orientation change from taking place.

For the best user experience, it's important to respond to this signal quickly (within 300ms total or so for all handlers combined).

The application can delay the orientation change (for example to make sure application's animations have completed) by pausing the current rotation and resuming it later after the UI was updated.

Note:

The value of orientation parameter might be the same as the current orientation in instances that the screen is about to be rotated 180 degrees.

This example assumes that the application has the Orientation property set to "Auto-orient" in Application tab of the bar-descriptor.xml file.
App::App() :
    m_pendingDirection(OrientationSupport::instance()->displayDirection())
{
   // m_label = ...
   // Setup the scene and so on.
}

// A slot connected to OrientationSupport::displayDirectionAboutToChange() signal
void App::onDisplayDirectionAboutToChange(DisplayDirection::Type displayDirection,
                                          UIOrientation::Type orientation)
{
    // We only want to delay the rotation when user initially rotates the device.
    if (m_pendingDirection != displayDirection) {
        // User rotated the device, let's pause the rotation; hide the label
        // And then resume rotaton.

        m_pendingDirection = displayDirection;

        OrientationSupport::instance()->
            setSupportedDisplayOrientation(
                    SupportedDisplayOrientation::CurrentLocked);

        // Update the UI here, for example.
        // Move the label off the screen during rotation.
        m_label->setTranslation(-100, -100);
    
        // Give animations a chance to complete before resuming rotation.
        // Set a timer for 200ms.
        QTimer::singleShot(200, this, SLOT(unlock()));
    }
}
// A slot invoked by the timer.
void App::unlock() {
    // Unlock orientation changes; this will cause the screen to rotate
    // According to device's physical orientation in space which will match
    // m_pendingDirection set in the onDisplayDirectionAboutToChange() slot.
    OrientationSupport::instance()->
        setSupportedDisplayOrientation(SupportedDisplayOrientation::All);
    // Also application can call OrientationSupport::requestDisplayDirection() to
    // rotate to specific direction, if needed.
}

The application can also prevent the orientation from occuring by changing the supportedDisplayOrientation property when handling this signal:

OrientationHandler {
    onDisplayDirectionAboutToChange: {
        // Prevent orientation change from happening for certain
        // directions.
        if (displayDirection == DisplayDirection.West) {
            OrientationSupport.supportedDisplayOrientation =
                SupportedDisplayOrientation.CurrentLocked
        }
    }
}
Parameters
displayDirection

The display direction.

orientation

The new UI orientation.

Since:

BlackBerry 10.0.0

void displayDirectionChanged (

Emitted when the display direction is changed in response to a device rotation or a change in the supported device orientation.

Parameters
displayDirection

The display direction.

Since:

BlackBerry 10.0.0

void orientationAboutToChange (

Emitted when the UI orientation is about to change in response to a device rotation or a change in the supported device orientation.

Parameters
orientation

The new UI orientation.

Since:

BlackBerry 10.0.0

void orientationChanged (

Emitted when the UI orientation is changed in response to a device rotation or a change in the supported device orientation.

This signal will not be emitted on 180 degree direction changes since the actual orientation does not change in this case.

Parameters
orientation

The new UI orientation.

Since:

BlackBerry 10.0.0

void rotationCompleted ()

Emitted when all orientation change-related activities have been completed.

This signal is emitted at the end of sequence of events caused by direction or orientation changes (unlike orientationChanged() which is only emitted when orientation has changed, which is not the case when device is rotated 180 degrees).

Since:

BlackBerry 10.0.0

void supportedDisplayOrientationChanged (

Emitted when supported display orientation changes.

Parameters
displayOrientation

The new supported device orientation.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus