OrientationHandler

This class is used for defining an orientation handler for orientation-related events in QML.

It can be used as an attached object to any UIObject for defining custom response for UI orientation changes.

This example assumes that application has Orientation property set to "Auto-orient" in Application tab of the manifest editor. 
Container {
    Button {
        text: "Change Orientation"
        onClicked: {
            if (OrientationSupport.orientation == UIOrientation.Portrait) {
                OrientationSupport.supportedDisplayOrientation = 
                    SupportedDisplayOrientation.DisplayLandscape;
            } else {
                OrientationSupport.supportedDisplayOrientation =
                    SupportedDisplayOrientation.DisplayPortrait;
            }
        }
    }
    Label {
        text: "Current UI Orientation: " + (handler.orientation == UIOrientation.Landscape ? "Landscape" : "Portrait")
    }
    attachedObjects: [
        OrientationHandler {
            id: handler
            onOrientationAboutToChange: {
                // set some UI to be shown during orientation change
                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: {
                // can update the UI after the orientation changed
            }
            onDisplayDirectionChanged: {
                // can perform actions based on the direction of the display
            }
        }
    ]
}

Inheritance

bb::cascades::BaseObject
bb::cascades::OrientationHandler

QML properties

orientation: bb::cascades::UIOrientation::Type [read-only]
displayDirection: bb::cascades::DisplayDirection::Type [read-only]
objectName: QStringInherited
parent: QObject [read-only]Inherited

Public Functions Index

bb::cascades::UIOrientation::Typeorientation () const
bb::cascades::DisplayDirection::TypedisplayDirection () const
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voidorientationAboutToChange (int orientation)
voidorientationChanged (int orientation)
voiddisplayDirectionChanged (int displayDirection)
voiddisplayDirectionAboutToChange (int displayDirection, int orientation)
voidrotationCompleted ()
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

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::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

QString objectNameInherited

This property is overridden from QObject.

As the objectName property is overridden from the QObject class, this signal will not be emitted if setObjectName() function is called directly on QObject.

The default value of this property is QString::null.

See:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parentInherited[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

Public Functions

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

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::DisplayDirection::Type displayDirection ()

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

void setObjectName (Inherited

Sets the objectName property.

Parameters
name

The new name for the object.
Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()Inherited

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (Inherited

Constructs an instance of BaseObject's subclass.

Parameters
parent

An optional parent, defaults to 0.
Since:

BlackBerry 10.0.0

Signals

void orientationAboutToChange (
  • intorientation,
  • )

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

Note:

Due to a work around for a Qt Core issues with accessing enum parameters from QML the argument of this signal has a type of int instead of bb::cascades::UIOrientation::Type.

void orientationChanged (
  • intorientation,
  • )

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

Note:

Due to a work around for a Qt Core issues with accessing enum parameters from QML the argument of this signal has a type of int instead of bb::cascades::UIOrientation::Type.

void displayDirectionChanged (
  • intdisplayDirection,
  • )

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

Note:

Due to a work around for a Qt Core issues with accessing enum parameters from QML the argument of this signal has a type of int instead of bb::cascades::DisplayDirection::Type.

void displayDirectionAboutToChange (
  • intdisplayDirection,
  • intorientation,
  • ,
  • )

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

Note that the value of orientation parameter could be the same as the current orientation in case the screen is about to be rotated 180 degrees.

Application can use this signal to perform activities before the rotation occures. Once this signal is handled the orientation change proceeds.

See:

OrientationSupport::displayDirectionAboutToChange()

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 change.

See:

OrientationSupport::rotationCompleted()

void creationCompleted ()Inherited

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node, or when an object is being constructed using its builder class.

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class. This signal is emitted to indicate that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

See:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0