MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Controlling rotation

Since the MeeGo 1.2 Harmattan device is used in both portrait and landscape orientations, you must ensure that your application behaves correctly in both modes. When a user physically rotates the device, the application can either change its orientation accordingly or remain locked in the default orientation.

When an application rotates its UI, the following need to be rotated by 90 degrees:

  • Contents of the application window. On the Harmattan platform, window content is not rotated by the system. The rotation needs to be done by code within your application.
  • UI components provided by the system, such as dialogs, virtual keyboard, and notifications banners. Since the components come from multiple sources, the system needs to be notified of the current orientation of the application.
  • Window decorations, such as the status bar (which shows, for example, the operator name and time) and possibly a toolbar (at the bottom of the screen).

On the Harmattan platform, Qt Quick Components and MeeGo Touch frameworks handle orientation changes automatically in your application. If you use other frameworks, you must do the required changes in the code of your application. For more information on the available UI frameworks, see Application development framework.

Consider showing a different UI layout for each orientation to match the shape of the screen. For example, items in a list can be shown in one column in portrait mode. If the orientation changes to landscape, the items can be shown in two columns to enhance visibility.

The native orientation (of the display hardware and X11) of the Harmattan system is landscape, even if the default of the Harmattan UI is portrait. Take this into account if you lock the UI orientation to the portrait mode.

Note: If you want to lock the UI orientation, consider selecting the portrait mode as the default mode. For most applications, it is the best option. However, for games and other such applications, the landscape orientation can be a more suitable default mode.

Controlling rotation in Harmattan

On the Harmattan platform, upper-level UI frameworks are responsible for orientation control. Using Qt Quick Components is the recommended option for creating new Harmattan applications.

A plain Qt application cannot handle orientation correctly on all platforms if it only uses the standard Qt APIs. If you use Qt Quick Components (QML) and MeeGo Touch (C++), the framework automatically changes the orientation of your application. To easily lock the orientation of your application to portrait or landscape mode, you can use the Qt Quick Components and MeeGo Touch APIs. For instructions on controlling rotation with other UI frameworks supported by Harmattan, see Using other UI frameworks.

Using Qt Quick Components

When you use the recommended Harmattan UI framework, Qt Quick Components, your application automatically switches between portrait and landscape orientations. Use the default behaviour if your application has a very simple UI layout that works for both landscape and portrait modes, such as a pannable vertical list that just fills the screen, whatever the size. For most applications, it is recommended that you implement different UI layouts to match the different geometry of the screen.

Defining the UI orientation

To define the orientation of each page in your application, use the Page component.

Note: Even though the orientation can vary within the application, it is not recommended.

Select one of the following values for orientationLock property of the Page component:

  • PageOrientation.Automatic - the page orientation is not locked.
  • PageOrientation.LockPortrait - the page orientation is locked in portrait.
  • PageOrientation.LockLandscape - the page orientation is locked in landscape.
  • PageOrientation.LockPrevious - the page orientation remains as in previous page.

The default value of the property is PageOrientation.Automatic.

Example

import QtQuick 1.1
import com.nokia.meego 1.0

PageStackWindow {
    ...
    initialPage: mainPage
    ...
}
 
Page {
    id: mainPage
    ...
    // Lock the screen orientation to portrait.
    orientationLock: PageOrientation.LockPortrait
    ...
}

For more information, see Qt Quick Components in MeeGo 1.2 Harmattan API documentation.

Creating portrait and landscape layouts

The following example shows how to create different layouts for portrait and landscape orientations of your application with the QML States. To create the example layouts:

  1. Select the Qt Quick Application template in Qt Creator.
  2. Replace the code in MainPage.qml with the code sample below:
import QtQuick 1.1
import com.nokia.meego 1.0

Page {
    id: mainPage

    state: (screen.currentOrientation == Screen.Portrait) ? "portrait" : "landscape"

    states: [
        State {
            name: "landscape"
            PropertyChanges { target: label1; text: qsTr("Landscape orientation") }
            PropertyChanges { target: label1; x: 20; y: 50}
            PropertyChanges { target: label2; x: 400; y: 50}
        },
        State {
            name: "portrait"
            PropertyChanges { target: label1; text: qsTr("Portrait orientation") }
            PropertyChanges { target: label1; x: 20; y: 200}
            PropertyChanges { target: label2; x: 20; y: 400}
        }
    ]

    transitions: Transition {
        PropertyAnimation { properties: "x,y"; duration: 1000 }
    }

    Label {
        id: label1
    }
    Label {
        id: label2
        text: qsTr("Another label")

    }
}

Declaring the properties of the components in different states using the QML States gives the application a nice declarative structure which is easy to maintain. For more information on States and Transitions, see QML Elements in MeeGo 1.2 Harmattan API reference.

Note: Even if this example uses the absolute positioning of the elements (that is, setting the x and y properties), this is not the only option for implementing layouts and it may not be the best choice for your application. You can also consider the following alternatives:

  • Use Anchors and Anchor Layouts and the related AnchorChanges along with the States.
  • Place your elements into Column and Row containers and re-parenting them when the state change occurs.

For more information and examples, see QML Elements in MeeGo 1.2 Harmattan API reference.

Using MeeGo Touch

When you use MeeGo Touch, your application automatically switches between portrait and landscape orientations. Thus, you do not need to take care of rotating your application yourself. Use the default behaviour if your application has a very simple UI layout that works for both landscape and portrait modes, such as a pannable vertical list that just fills the screen, whatever the size. For most applications, it is recommended that you implement different UI layouts and optimise the UI for the different geometry of the screen.

To lock the orientation of the application to portrait or landscape mode, use the MWindow and MWidget classes. For more information, see libmeegotouch library in the Platform API reference.

Using other UI frameworks

If you are using other UI frameworks in your Harmattan application (such as OpenGL ES, QGraphicsView, Plain QML, or QtWebKit), it is recommended that you create a Qt Quick Components or MeeGo Touch wrapper for your code. Using QWidget in Harmattan applications is generally not recommended, because the UI elements are too small and not suitable for touch-screen interaction. Additionally, QWidgets are quite heavy to paint compared to other graphical Qt objects. Even if it is technically possible to wrap QWidgets as QtGraphicsProxyWidgets and then into MeeGo Touch or QML, this causes performance issues. In most cases, rotating the QWidgets is just too slow and heavy.

For more information on these frameworks and their limitations, see QWidget, QGraphicsView, and plain Qt Quick in the Application development framework section.

The following table presents instructions for controlling rotation with the non-recommended UI frameworks.

Controlling rotation in other UI frameworks
UI framework Recommended option Other alternatives
Web applications / Qt WebKit Make a Qt Quick Components or MeeGo Touch wrapper around your application.
  • In Qt Quick Components: use the QML WebView element
  • In MeeGo Touch, use the QGraphicsWebView class.

For an example, see Example of wrapping a web application into QML.

 Rotate the content yourself.
  • Manually set the X11 orientation property.
  • Show in full-screen, no status bar.

For an example, see Example of rotating a web application manually.
QGraphicsView Make a Qt Quick Components or MeeGo Touch wrapper around your application. Both MeeGo Touch and QML are based on QGraphicsView, so showing such content is easy.

For an example, see Example of wrapping a web application into QML.

 Rotate the content yourself, it is easy in QGraphicsView.
  • Manually set the X11 orientation property.
  • Show in full-screen, no status bar.

For an example, see Example of rotating a web application manually.
OpenGL ES Consider making a MeeGo Touch wrapper around your application. If you lock to one orientation only (as, for example, games typically do):
  • Rotate content by 90 degrees if needed.
  • Set the X11 properties if you show the application in the portrait mode (not needed for the landscape mode).
Plain QML Make a small Qt Quick Components wrapper and show your original QML code within a Qt Quick Components Page.
Small to moderate use of QWidgets Consider porting to MeeGo Touch, if you only have a few QWidgets in your UI and the layouts are relatively simple. For many widget types, the MeeGo Touch API is very similar to QWidget and in many cases, a simple search-and-replace does 90 per cent of the job.
Heavy usage of QWidgets Completely rewrite the UI of the application.

Further information

For more information on rotation control, see the following links: