Doc - Update information on Maemo. Add information about using QEMU.

Reviewed-by: Christian Kandeler

doc/qtcreator.qdoc

@@ -1744,10 +1744,23 @@
 
     \endlist
 
-    \section2 Building for Maemo
+    For more information about using the Qt Simulator, see the
+    \l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
+
+    \section1 Building for Maemo
 
     \list 1
 
+        \o Build and run the application for \l{Building for Qt Simulator}{Qt Simulator}.
+
+        \o Build and run the application for \l{Using the Maemo Emulator}{Maemo Emulator}.
+
+        \note The Maemo emulator support requires the Nokia Nokia N900 PR1.2 update.
+
+        \o If no problems are found, build and run the application for a device:
+
+        \list 1
+
         \o Set up the MADDE development environment and specify a connection
         to the device. For more information, see
         \l{Setting Up Development Environment for Maemo}.
@@ -1756,18 +1769,22 @@
 
         \o Click the \gui Run button.
 
+        \endlist
+
+    \endlist
+
         Qt Creator uses the compiler specified in the MADDE toolchain to
         build the application.
 
-        The application is automatically copied to the device and executed
-        there. The application views are displayed on the N900. Command-line
-        output is visible in the Qt Creator \gui {Application output} view.
+        Qt Creator generates an installation package, installs in on the device,
+        and executes it. The application views are displayed on the Nokia N900.
+        Command-line
+        output is visible in the Qt Creator \gui {Application Output} view.
 
         Debugging also works transparently.
 
-    \endlist
 
-    \section2 Building for Symbian
+    \section1 Building for Symbian
 
     \list 1
 
@@ -1963,7 +1980,7 @@
             \o The \l{glossary-project-qt}{Qt version} you want to use to
                build your project. For more information, see
                \l{Selecting the Qt version}.
-            \o The toolchain required to build the project.
+            \o The tool chain required to build the project.
             \o By default, projects are built in a separate directory
                from the source directory, as \l{glossary-shadow-build}{shadow builds}.
                This keeps the files generated for each target platform separate.
@@ -4960,36 +4977,42 @@
 
     Maemo is a software platform developed by Nokia for smartphones and
     Internet Tablets. The Maemo SDK provides an open development environment
-    for different applications on top of the Maemo platform.
-    Maemo 5 is based on the Linux 2.6 operating system. You can find more
-    information about the Maemo platform \l{http://maemo.org/intro/platform/}{here}.
+    for different applications on top of the Maemo platform. The necessary
+    tools from the Maemo SDK are also included in the Nokia Qt SDK.
+    The whole tool chain that you need to create, build, debug, run, and deploy
+    Maemo applictions is installed and configured when you install the Nokia
+    Qt SDK.
+
+    Maemo 5 is based on the Linux 2.6 operating system. For more
+    information about the Maemo platform, see
+    \l{http://maemo.org/intro/platform/}{Software Platform} on the Maemo web site.
 
 
     \section1 Hardware and Software Requirements
 
     To build and run Qt applications for Maemo, you need the following:
     \list
-       \o  An N900 device with updates installed.
-       \o  The MADDE cross-platform Maemo development
-           tool.
+       \o  Nokia N900 device with PR1.2 or later installed.
+       \o  MADDE cross-platform Maemo development
+           tool (installed as part of the Nokia Qt SDK).
 
            For more information about MADDE pertaining to its
            installation, configuration, and deployment on the device, see
           \l{http://wiki.maemo.org/MADDE}{Introduction to MADDE}.
 
-       \o  An IP address for the device.
+       \o  IP address for the device.
 
-           In order to setup the device IP address, you need to install
-           PC Connectivity or implement it using CLI. More information about PC
-           Connectivity can be found
+           To set up the device IP address, you need to install
+           PC Connectivity or implement it using CLI. For more information about PC
+           Connectivity, see
           \l{http://pc-connectivity.garage.maemo.org/2nd_edition/node3.html#SECTION00032300000000000000}
-           {here}.
+           {Windows} on the PC Connectivity web site.
     \endlist
 
     To deploy and run Qt applications on Maemo devices, you need the
     following:
     \list
-       \o The Nokia USB drivers that come, for example with, PC Suite, if you use
+       \o Nokia USB drivers that come with PC Suite, for example, if you use
        a USB connection to run applications on the device.
        \o Qt installed on the device. Recent images should have Qt pre-installed.
     \endlist
@@ -5004,9 +5027,9 @@
     \note The only supported build system for Maemo in Qt
     Creator is qmake.
 
-    \section1 Setting Up the N900
+    \section1 Setting Up the Nokia N900
 
-    You can connect your device to your development PC using either an USB or a
+    You can connect your device to your development PC using either a USB or
     WLAN connection.
 
     For the device, you need to use a tool called Mad Developer to create the
@@ -5014,71 +5037,86 @@
     diagnostics functions but is essential for creating connections between the
     device and your development PC.
 
-    For the development PC, you need to set up the N900 as a network device.
+    To use a WLAN connection, you must activate WLAN on the device and connect
+    it to the same WLAN as the development PC. The network address is displayed
+    in the Mad Developer.
+
+    To use an USB connection, you need to set up the Nokia N900 as a network device
+    on the development PC.
 
-    \note If you plan to connect your development PC to the N900 only over WLAN, you can
+    \note If you plan to connect your development PC to the Nokia N900 only over WLAN, you can
     ignore the USB-specific parts in the following sections.
 
-    \section2 Installing the Mad Developer Package
+    \section2 Installing and Configuring Mad Developer
 
     To install Mad Developer on your device, you need to add an application
-    catalogue (repository) to the list of catalogues your device checks for
+    catalogue to the list of catalogues your device checks for
     installable software, and install the actual Mad Developer software
-    package. This is done according to the following
-    steps:
+    package. After the installation, you must start Mad Developer and configure
+    a connection between the development PC and the device.
+
+    To install and configure Mad Developer:
+
      \list 1
-         \o Start the application manager
+         \o On the Nokia N900, select \gui {Application manager > Application catalogs
+         > New}.
+
+         \o Specify the following settings:
+
+         \image qtcreator-app-manager-extras-devel-screenshot.png
 
-            Enter the data as displayed in the screenshot below.
+            \list a
+
+            \o \gui {Catalogue name}: \bold devel
 
-            \note The complete web address is
+            \o \gui {Web address}:
             \l http://repository.maemo.org/extras-devel
 
-            \image qtcreator-app-manager-extras-devel-screenshot.png
+            \o \gui Distribution: \bold fremantle
 
-         \o Select \gui{Download} > \gui{Development} > \gui{mad-developer}.
+            \o \gui Components: \bold {free non-free}
 
-            The screenshots below shows the process for selecting the
-            \gui{mad-developer}:
+            \endlist
 
-            \image qt-creator-app_manager_screenshot1.png
-            \image qt-creator-app_manager_screenshot2.png
+         \o Click \gui Save to add the catalogue.
 
+         \o Select \gui{Download} > \gui{Development} > \gui{mad-developer}
+         to install the Mad Developer software package.
+         \o Click \gui {Mad Developer} to start the Mad Developer application.
 
-         \o Install the Mad Developer software package.
-         \o Start the Mad Developer application.
-     \endlist
+         \o To use a WLAN connection, activate WLAN on the device and connect
+         to the same network as the development PC. You can see the network
+         address in the \gui wlan0 field.
+
+         \o To use an USB connection:
 
-   \note If you are using Microsoft Windows as development host, you must
+         \list a
+
+         \o If you are using Microsoft Windows as development host, you must
          change the driver loaded for instantiating the connection.
-         For this click \gui{Manage USB} and select \gui{Load g_ether}.
+         In the Mad Developer, select \gui{Manage USB} and select \gui{Load g_ether}.
 
-    Follow the steps mentioned below to set up the USB settings:
-    \list 1
-       \o Click \gui Edit in the usb0 row and confirm with \gui Configure.
+         \o To set up the USB settings, click \gui Edit on the \gui usb0 row and
+         confirm by clicking \gui Configure.
 
-          \note By default, you do not need to make changes. The usb0 row
+          \note By default, you do not need to make changes. The \gui usb0 row
           displays the IP address 192.168.2.15.
 
-       \o Select \gui{Developer Password} to generate a password for a freshly
-          created user called "developer". The password stays valid for as long
-          the password generation dialog is open.
+          \endlist
 
-          Refer to the screenshot below as an example.
+       \o Select \gui{Developer Password} to generate a password for a freshly
+          created user called \bold developer. The password stays valid for as long
+          as the password generation dialog is open. You enter the password when
+          you configure the connection in Qt Creator.
 
           \image qtcreator-mad-developer-screenshot.png
     \endlist
 
-    \section2 Establishing the USB Connection
+    \section1 Setting Up Network Connectivity on Development PC
 
-    Connect your device to the development PC via the USB cable. A dialog
-    pops up asking for the mode to use. Choose \gui{PC suite mode}.
-
-    \note If you experience connection problems due to a USB port issue, switch
-     to a different port.
-
-
-    \section1 Setting Up Connectivity
+    Use the network configuration tools on your platform to specify the
+    connection to the device on the development PC. You need to do this
+    only if you use an USB connection.
 
     \section2 Linux
 
@@ -5088,7 +5126,7 @@
 
     \note If you have changed the IP address of the device when configuring
     Mad Developer, you need to reflect those changes in your development PC USB
-    network settings as well.
+    network settings.
 
     Run the following command in a shell as root user:
                   \c{ifconfig usb0 192.168.2.14 up}
@@ -5101,95 +5139,174 @@
     first dialog and \gui{Install the software automatically} in the second
     dialog.
 
-    Open the Network Connections window. The just installed Linux USB Ethernet
-    connection is now displayed as a new Local Area Connection.
+    To specify a network connection:
+
+    \list 1
 
-    Perform the same steps through the Network configuration tools available
-    with the operating system.
+    \o Open the Network Connections window.
 
-    Change the IP to be set statically and enter the following values:
+    \o Select the Linux USB Ethernet
+    connection that is displayed as a new Local Area Connection.
+
+    \o Edit the \gui {Internet Protocol Version 4 (TCP/IPv4)} properties
+    to specify the IP address for the connection.
+    In the \gui {Use the following IP address} field, enter the following values:
     \list
-       \o  IP Address: 192.168.2.14
-       \o  SubnetMask: 255.255.255.0
-       \o  Default gateway: 192.168.2.15
+       \o  \gui {IP Address}: \bold {192.168.2.14}
+       \o  \gui SubnetMask: \bold {255.255.255.0}
+       \o  \gui {Default gateway}: leave this field empty
+    \endlist
+
     \endlist
 
-    Accept these settings and close the Network Configuration. Depending on
+    Depending on
     your version of Microsoft Windows you may have to unplug and re-plug the
-    N900 to reload the driver with its configuration accordingly.
+    Nokia N900 to reload the driver with its configuration accordingly.
 
-    \section2 Setting Up MADDE
+    \section1 Setting Up MADDE
 
     If you install Nokia Qt SDK, the MADDE package is installed and
-    configured automatically on your development PC and you can omit this step.
+    configured automatically on your development PC and you can omit this task.
+
+    \list 1
+
+    \o Download the MADDE installer file for your platform from the
+    \l{http://wiki.maemo.org/MADDE}{MADDE} site.
+
+    \o Execute the installer and follow the instructions.
 
-    After having downloaded the MADDE installer file for your platform from
-    \l{http://wiki.maemo.org/MADDE}{here}, execute it and follow the
-    instructions. The package will be installed. Then run:
-    \c{mad-admin list targets} to see which targets are available.
-    Install the target that starts with "fremantle" by using the command:
+    \o To see which targets are available, run \c{mad-admin list targets}.
+
+    \o To install the target that starts with the string \bold fremantle, use the command:
     \c{mad-admin create fremantle-qt-xxx}
 
+    \o In Qt Creator, register the MADDE tool chain:
+
+       \image qtcreator-screenshot-toolchain.png
+
+        \list a
+
+            \o Select \gui Tools > \gui Options... > \gui Qt4 > \gui{Qt Versions}.
+
+            \o Click \inlineimage qtcreator-windows-add.png,
+            to add a new Qt version.
+
+            The \gui{qmake Location} is the qmake
+            executable in \c{<MADDE dir>/targets/<fremantle target>/bin}.
+
+        \endlist
+
+    \endlist
+
     When you have installed the target, you have a toolchain and a sysroot
     environment for cross-compiling.
 
-    \section1 Setting Up Qt Creator
+    \section1 Configuring Connections in Qt Creator
+
+    To be able to run and debug applications on the Maemo emulator and
+    devices, you must set up a connection to the emulator and the device in the
+    Qt Creator build and run settings. If you install Nokia Qt SDK, the
+    necessary software is installed and configured automatically and you
+    only need to configure a connection to the device.
+
+    You can protect the connections between Qt Creator and the Maemo emulator
+    or a device by using either a password or an SSH key. You must always
+    use a password for the initial connection, but can then deploy an SSH
+    key and use it for subsequent connections. If you use a password, you
+    must generate it in Mad Developer and enter it in Qt Creator every time
+    you connect to the Maemo emulator or to a device.
 
-    Set up a connection to the device in the
-    Qt Creator build and run settings, as follows:
+    If you do not have an SSH key, you can create it in Qt Creator. For more
+    information, see \l{Generating SSH Keys}.
+
+    To configure connections between Qt Creator and the Maemo emulator or
+    device:
 
     \list 1
-        \o  If you install Qt Creator separately, you must register the
-        MADDE toolchain:
+
+        \o If you install the Maemo emulator (QEMU) separately, you must
+           specify parameters to access it:
 
             \list a
 
-            \o Select \gui Tools > \gui Options > \gui Qt4 > \gui{Qt Versions}.
+            \o Start Mad Developer in the emulator.
 
-            \o Click \inlineimage qtcreator-windows-add.png,
-            to add a new Qt version.
+            \o Click \gui {Developer Password} to generate a password for
+            the connection.
 
-            The \gui{qmake Location} is the qmake
-            executable in \c{<MADDE dir>/targets/<fremantle target>/bin}.
+            \o In Qt Creator, select \gui {Tools > Options... > Projects >
+            Maemo Device Configurations > Add} to add a new configuration.
+
+            \image qtcreator-maemo-emulator-connection.png
+
+            \o In the \gui {Configuration name} field, enter a name for
+            the connection.
+
+            \o In the \gui {Device type} field, select \gui {Local simulator}.
+
+            \o In the \gui {Authentication type} field, select \gui Password
+            for the initial connection.
+
+            \o In the \gui Password field, enter the password from the Mad
+            Developer for the initial connection.
+
+            You can use the default values for the other fields.
+
+            \o Click \gui Test to test the connection.
+
+            \o To avoid having to specify the password every time you connect
+            to the Maemo emulator, click \gui {Deploy Key...} and select
+            the file that contains your public key.
+
+            \o When you have deployed the key to the device, change the
+            configuration to use the SSH key for protection.
 
-            \image qtcreator-screenshot-toolchain.png
+            \image qtcreator-maemo-emulator-connection-key.png
+
+            The default location of the private key file is displayed in the
+            \gui {Private key file} field.
 
             \endlist
 
-            If you installed the Nokia Qt SDK, you can omit this step.
+            If you installed the Nokia Qt SDK, a connection has been configured
+            and you only need to specify the password and deploy the SSH key.
 
         \o  To deploy applications and run them remotely, specify parameters
             for accessing devices:
 
             \list a
 
-            \o Select \gui Tools > \gui Options > \gui Qt4 >
-            \gui{Maemo Devices} and add a new configuration.
+            \o Connect your device to the development PC via an USB cable or
+            a WLAN. For an USB connection, you are prompted to select the mode
+            to use. Choose \gui{PC suite mode}.
 
-            \image qtcreator-screenshot-devconf.png
+            \note If you experience connection problems due to a USB port issue,
+            switch to a different port or use WLAN to connect to the device.
 
+            \o Select \gui Tools > \gui Options... > \gui Projects >
+            \gui{Maemo Device Configurations > Add}, and add a new configuration for a
+            \gui {Remote device}.
 
-            \note The password is the one MADDE Developer displays on the
-            device.
+            \image qtcreator-screenshot-devconf.png
 
-            \o Click \gui Test to check whether the device can be accessed
-            properly.
+            \o In the \gui {Host name} field, enter the IP address from the
+            \gui usb0 or \gui wlan0 field in Mad Developer.
 
-             It is recommended that you use the password-based login
-            only to deploy your public SSH key to the device
-            (using the \gui{Deploy Key} button) and then switch to key-based
-            authentication.
+            \o Specify the other settings in the same way as for a Maemo emulator
+            connection.
+
+            \o Click \gui Test to test the connection.
 
             \o Click \gui OK to close the dialog.
 
             \endlist
 
-         \o To specify build settings:
+         \o To specify build and run settings:
 
             \list a
 
                 \o Open a project for an application you want to develop for your
-                N900.
+                Nokia N900.
 
                 \o Click \gui Projects to open the projects mode.
 
@@ -5198,19 +5315,184 @@
                  \image qtcreator-screenshot-build-settings.png
 
                  \o In the \gui{Run Settings} section, click \gui Add to add a new
-                 run configuration on the Maemo device.
+                 run configuration.
 
                  \o Set a name and select the device configuration.
 
                  \image qtcreator-screenshot-run-settings.png
 
+                 \note You can either add separate run settings for both the Maemo
+                  emulator connection and the device connection or select the
+                  \gui {Device configuration} before you run the application.
+
              \endlist
 
          \endlist
 
+         \section2 Generating SSH Keys
+
+         If you do not have an SSH public and private key pair, you can generate it
+         in Qt Creator. You can specify key length and the key algorithm, RSA or DSA.
+         If you only use the keys to protect connections to the Maemo emulator or
+         device, you can use the default values.
+
+         \list 1
+
+             \o Select \gui {Tools > Options... > Projects > Maemo Device Configurations
+             > Generate SSH Key...}.
+
+             \o Click \gui {Generate SSH Key}.
+
+             \image qtcreator-ssh-key-configuration.png "SSH Key Configuration dialog"
+
+             \o Click \gui {Save Public Key...} to select the location to save the
+             public key.
+
+             \o Click \gui {Save Private Key...} to specify the location to save the
+             private key.
+
+             \o Click \gui Close to close the dialog.
+
+         \endlist
+
 */
 
 
+/*!
+    \contentspage index.html
+    \previouspage creator-usability.html
+    \page creator-maemo-emulator.html
+    \nextpage creator-debugging.html
+
+    \title Using the Maemo Emulator
+
+    The Maemo emulator emulates the Nokia N900 device environment. You can test
+    applications in conditions practically identical to running the application
+    on a Nokia N900 device. You can test user interaction by using the keypad and
+    touch emulation.
+
+    \note The Maemo emulator support requires the Nokia N900 PR1.2 update.
+
+    To test the application UI, user interaction with the application, and
+    functionality that uses the mobility APIs, use the Qt Simulator,
+    instead. For more information, see the
+    \l{http://doc.qt.nokia.com/qt-simulator-beta/index.html}{Qt Simulator Manual}.
+
+    The Maemo emulator is installed and configured as part of the Nokia Qt SDK
+    package. You can also install and configure the MADDE environment and
+    Maemo emulator separately. For more information, see
+    \l{Setting Up Development Environment for Maemo}.
+
+    \section1 Starting the Maemo Emulator
+
+    The \gui {Start Maemo Emulator} button is visible if you have a project
+    open in Qt Creator for which you have added the Maemo build target.
+
+    To start the Maemo emulator:
+
+    \list 1
+
+    \o Click
+    \inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
+    .
+
+    \o Select \gui {Mad Developer} on the Maemo emulator, to start the Mad Developer
+    application
+
+    \o If you have not deployed an SSH key to protect the connection between
+    Qt Creator and the Maemo emulator, select \gui {Developer Password} to generate
+    a password.
+
+    \o In Qt Creator, enter the password in the connection settings:
+    \gui {Tools > Options... > Projects > Maemo Device Configurations}.
+
+    \endlist
+
+    Test your application on the Maemo emulator as on a device. For a list of
+    keyboard shortcuts that you can use to emulate Nokia N900 keys and functions, see
+    \l {Emulating Nokia N900 Keys}.
+
+    \section1 Emulating Nokia N900 Keys
+
+    The following table summarizes the keyboard shortcuts that you can use
+    to emulate Nokia N900 keys and functions.
+
+    \table
+        \header
+            \o Nokia N900 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
+        \row
+            \o Ctrl
+            \o Left Ctrl key
+        \row
+            \o Mode
+            \o Left Alt key
+        \row
+            \o Power
+            \o Esc
+        \row
+            \o Keypad slider open and close
+            \o F1
+        \row
+            \o Keypad lock
+            \o F2
+        \row
+            \o Camera lens open and close
+            \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
+            \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
+
+
+*/
+
 
 /*!
     \contentspage index.html