Home · All Classes · Main Classes · Deprecated

Screen rotation

MeeGo Touch applications can be used in both landscape and portrait orientations. You can rotate applications to four different orientation angles: 0, 90, 180 and 270 degrees clockwise. For more information on coordinate systems and related angles, see Scene and scene windows.

By default, MeeGo Touch applications automatically rotate to the appropriate orientation angle when needed. It just works.

Checking or setting the current orientation

Some applications may need to allow checking or manually setting the current orientation. MWindow provides the following methods and signals for this purpose:

MWindow::orientation() Returns the current orientation (portrait or landscape) of the GUI.
MWindow::setLandscapeOrientation() Puts the GUI in landscape orientation.
MWindow::setPortraitOrientation() Puts the GUI in portrait orientation.
MWindow::orientationChanged() Signal emitted when the orientation of the GUI changes (from landscape to portrait or vice-versa).
MWindow::orientationChangeFinished() Signal emitted when the orientation change animation (also known as rotation animation) ends.

You can also deal with orientation angles directly. However, take into consideration which angles are relevant for the host device. For more information, see the following sections.

MWindow::orientationAngle() Returns the current orientation angle (i.e. 0, 90, 180 or 270 degrees clockwise) of the GUI.
MWindow::setOrientationAngle() Sets the current orientation angle of the GUI.
MWindow::orientationAngleChanged() Signal emitted when the orientation angle changes.

MSceneManager provides a similar API. If an MWindow has a scene manager, all the methods and signals mentioned above simply mirror those of its scene manager. This is due to the fact that MWindow itself is not rotated but the items (in other words, scene windows) in the displayed scene. For more information, see Scene and scene windows.

When the orientation changes, an MOrientationChangeEvent event is also sent to all affected widgets. To easily handle this event in your widget, reimplement the following method:

MWidget::orientationChangeEvent(MOrientationChangeEvent *event)

Orientation angles supported by the host device

Different devices allow different orientation angles. A mobile phone, for instance, can support the angle 270 but not 90, which probably means that 270 is the portrait orientation angle that puts its earpiece on top of the GUI and its mouthpiece below the GUI.

If a device has a hardware keyboard, the allowed angles also depend on whether the keyboard is open or not. For example, a device supports angles 0 and 270 when its hardware keyboard is closed and only angle 0 when it is open.

To check whether a given orientation angle is supported by the host device (and is relevant for it), you can use the following method:

bool MDeviceProfile::orientationAngleIsSupported(M::OrientationAngle angle, bool isKeyboardOpen);

Overriding automatic rotation

When the orientation of a device changes (within its set of supported orientation angles), the orientation is automatically applied to its MeeGo Touch application.

You can override automatic rotation by locking the GUI of the application to a specific angle or orientation. You can lock the GUI to any orientation angle whether it is supported by the device or not. Note that if you just set an orientation (using a method such as MWindow::setOrientationAngle()) without locking it, the orientation of your GUI changes according to the device orientation.

To lock the GUI to a specific orientation (portrait or landscape), use the following methods:

MWindow::lockOrientation() Locks the GUI into its current orientation.
MWindow::unlockOrientation() Unlocks the GUI from its current orientation. If the device orientation changes after this point, the orientation of the GUI changes accordingly.
MWindow::isOrientationLocked() Returns whether the orientation is locked.
MWindow::setOrientationLocked() Locks the GUI into its current orientation or unlocks the GUI orientation.

To be more restrictive and lock the GUI to a specific angle:

MWindow::lockOrientationAngle() Locks the GUI to its current orientation angle.
MWindow::unlockOrientationAngle() Unlocks the GUI from its current orientation angle. If the device orientation changes after this point, the orientation of the GUI changes accordingly.
MWindow::isOrientationAngleLocked() Returns whether the orientation angle is locked.
MWindow::setOrientationAngleLocked() Locks the GUI to its current orientation angle or unlocks the GUI orientation angle.

Locking the orientation is not recommended because it breaks expected behaviour and usability. For example, users might wonder why the application does not rotate like the others. It also limits the flexibility of your GUI. However, locking the orientation of the GUI can be useful and valid if it is intended to be used in only one specific orientation or angle.

A rotation animation, step-by-step

  1. MSceneManager::setOrientationAngle() is called (for example, due to a change in the device's orientation angle)
  2. MSceneManager starts a rotation animation
  3. During the rotation animation MSceneManager does the following:
    1. Emission of MSceneManager::orientationAboutToChange().
    2. Sending of MOrientationChangeEvent to all widgets in the scene.
      • Causes MWidgetView::applyStyle() to be called on views of all affected widgets.
      • Causes MLayouts to switch to the layout policy of the new orientation.
    3. Resizing and repositioning of all scene windows to the new orientation.
    4. Emission of MSceneManager::orientationChanged() (if applicable).
    5. Emission of MSceneManager::orientationAngleChanged().
  4. MSceneManager's rotation animation finishes. MSceneManager::orientationChangeFinished() is emitted.

Copyright © 2010 Nokia Corporation
MeeGo Touch