/****************************************************************************
**
** Copyright (c) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage creator-build-process-customizing.html
    \page creator-maemo-emulator.html
    \nextpage creator-testing.html

    \title Using Maemo or MeeGo Harmattan Emulator

    The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
    of the Qt 4 SDK. After they are installed, you can start them from \QC.

    The Maemo 5 emulator emulates the Nokia N900 device environment. You can
    test applications in conditions practically identical to running the
    application on a Nokia N900 device with software update release 1.3
    (V20.2010.36-2).

    The MeeGo Harmattan emulator emulates the Nokia N9 device environment.

    With the emulators, you can test how your application reacts to hardware
    controls, such as the power button, and to the touch screen.

    To test the application UI, user interaction with the application, and
    functionality that uses the mobility APIs, use \QS,
    instead. For more information, see the
    \l{http://doc.qt.digia.com/qtsimulator/index.html}{\QS Manual}.

    The difference between \QS and the emulators is that when you
    compile your application binary for \QS, it is compiled against a
    host library. The binary run on the emulator is compiled for the actual
    device, using the Maemo 5 or Harmattan tool chain.

    \section1 Starting the Emulator

    The \gui {Start MeeGo Emulator} button is visible if you have a project
    open in \QC for which you have added a \l{glossary-buildandrun-kit}{kit}
    with Maemo or MeeGo Harmattan device type.
    It starts the Maemo or MeeGo Harmattan emulator, depending
    on the selected kit.

    To start the emulator, click
    \inlineimage qtcreator-maemo-emulator-button.png "Start MeeGo Emulator button"
    .

    Test your application on the emulator as on a device. For a list of
    keyboard shortcuts that you can use to emulate keys and functions, see
    \l {Emulating Device Keys}.

    \section1 Rendering Graphics

    The emulators support OpenGL to improve graphics rendering. Hardware
    acceleration produces better results than software rendering. By default,
    \QC automatically detects, whether hardware acceleration is
    supported on the development PC and tries to use it. However, sometimes
    the results of the automatic detection are not reliable, and
    hardware acceleration might be selected even if it is actually not
    available on the development PC. This causes the emulator to crash.

    If the emulator crashes, you are asked whether you want to try software
    rendering, instead.

    To specify the OpenGL mode, select \gui {Tools > Options > Linux Devices
    > MeeGo Qemu Settings}.

    \section1 Emulating Device Keys

    The following table summarizes the keyboard shortcuts that you can use
    to emulate device keys and functions.

    \table
        \header
            \o Device Key
            \o Keyboard Shortcut
        \row
            \o \list
                \o Alphabet keys
                \o Comma (,)
                \o Period (.)
                \o Space
                \o Arrow keys
                \o Enter
                \o Backspace
               \endlist
            \o Respective keys on the development PC keyboard.
        \row
            \o Shift
            \o Left Shift key (Maemo 5)

               Shift (Harmattan)
        \row
            \o Ctrl
            \o Left Ctrl key (Maemo 5)

               Ctrl (Harmattan)
        \row
            \o Mode
            \o Left Alt key (Maemo 5)

               Alt (Harmattan)
        \row
            \o Power
            \o Esc
        \row
            \o Keypad slider open and close
            \o F1
        \row
            \o Keypad lock (Maemo 5 only)
            \o F2
        \row
            \o Camera lens open and close (Maemo 5 only)
            \o F3
        \row
            \o Camera focus
            \o F4
        \row
            \o Camera take picture
            \o F5

            \note The actual camera functionality is not emulated.
        \row
            \o Stereo headphones connect and disconnect (Maemo 5 only)
            \o F6
        \row
            \o Volume down
            \o F7
        \row
            \o Volume up
            \o F8
        \row
            \o Accelerometer x axis, negative
            \o 1
        \row
            \o Accelerometer x axis, positive
            \o 2
        \row
            \o Accelerometer z axis, negative
            \o 4
        \row
            \o Accelerometer z axis, positive
            \o 5
        \row
            \o Accelerometer y axis, negative
            \o 7
        \row
            \o Accelerometer y axis, positive
            \o 8

    \endtable

    \note Each press of the accelerometer key turns the acceleration by 50
    percent.

    \section1 Closing the Emulator

    To close the emulator, click the X at the top right corner of the device
    emulator view. The emulator interprets this as a press of the power button
    and displays the text \e {Shutting down} in the emulator window title pane.
    The emulator closes shortly after this.

    You can also select the \gui {Start MeeGo Emulator} button to close the
    emulator. This is a faster way to close the emulator, because it does not
    wait for the operating system running on the emulated machine to shut down,
    but this also means that it is less safe.

*/