OrientationHandler

Since: BlackBerry 10.0.0

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
            }
        }
    ]
}


Overview

Inheritance

bb::cascades::BaseObject
bb::cascades::QmlOrientationHandler

QML properties

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

Public Functions Index

bb::cascades::DisplayDirection::TypedisplayDirection () const
bb::cascades::UIOrientation::Typeorientation () 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

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

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.

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

QString objectNameInherited

This property is overridden from QObject.

See also:

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

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

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

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

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

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

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.

void creationCompleted ()Inherited

Emitted 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 indicates 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 also:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-26



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus