diff --git a/doc/src/symbian/creator-deployment-symbian.qdoc b/doc/src/symbian/creator-deployment-symbian.qdoc new file mode 100644 index 00000000000..9d8e9733da8 --- /dev/null +++ b/doc/src/symbian/creator-deployment-symbian.qdoc @@ -0,0 +1,372 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// 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-deployment.html + \page creator-deployment-symbian.html + \nextpage creator-deployment-maemo.html + + \title Deploying Applications to Symbian Devices + + This section describes how to create installation packages that meet the + requirements for installing applications to Symbian devices. + + \section1 Creating SIS Files + + When you deploy the application for the \gui{Symbian Device} target, \QC + automatically generates a Symbian installation system (SIS) file + in the project folder. You can deliver the installation file to users for + installation on Symbian devices. + + The name of the installation file is displayed in the \gui {Installation file} + field in the \gui {Run Settings}. In the \gui {Installation drive} field, select the drive on the device + to install the application to. To suppress notifications on the device during the + installation, select the \gui {Silent installation} check box. If the silent + installation fails, \QC attempts installation again, this time displaying + notifications and error messages. + + To create a SIS package without copying it to the device (for example, to submit it + to \e {Application Signing Services for Ovi Store} or \e {Symbian Signed}), + create a deploy configuration that contains only the + \gui {Create SIS Package} step. + + \image qtcreator-run-settings-create.png "Create SIS Package step" + + + \section1 Signing SIS Files + + Only installation files signed with a certificate and private key are + allowed to be installed onto Symbian devices. By default, \QC + self-signs the installation file. This self-signing allows you to install + the application on a mobile device but places limits on what you can do + with the installation file, including: + \list + \o Self-signed applications cannot access the more sensitive + \l{Capabilities and Signing}{capabilities} of the mobile device. + \o Security warnings will be displayed when you install the self-signed + application on a mobile device. + \o Self-signed applications cannot be published to Ovi + Store. + \endlist + + To get around these limitations, you need to go through the Symbian Signed + or Application Signing Services for Ovi Store. The Symbian Signed organisation + manages a public key + infrastructure to provide public authentication of the information in the + application signing certificates. Their security partner can validate your + certificate and give you a Publisher ID. Then, when you sign an + application, other people can be confident that the information in your + certificate is correct and that the application does actually come from you. + + Application Signing Services for Ovi Store is a variant of the Symbian + Signed certification provided by Ovi + Publishing. It is limited to the Basic and System capability sets + (Express Signing). Participants can submit an unsigned SIS file to Ovi + Publishing for signing. For more information about how + to participate, see + \l {http://www.developer.nokia.com/Community/Wiki/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store}. + + There are also options that do not require you to get a Publisher ID. For + more detail about how the Symbian Signed process works, see + \l{https://www.symbiansigned.com}{Symbian Signed}. + + When you have your own certificate and private key, you can specify them in + the \gui{Create SIS Package} step in the \gui {Run Settings}. + + \image qtcreator-qt4-symbian-signing.png + + + If your private key is protected by a passphrase, \QC asks you for the + passphrase when the package is signed and offers to store it. However, storing + passphrases in \QC presents a security risk. To make \QC forget + all saved passphrases, click \gui {Reset Passphrases}. + + \section2 Capabilities and Signing + + Capabilities allow the Symbian platform to control access by applications to + the functionality provided by the platform APIs. Access to capabilities is + determined by the device configuration and how the application has been signed. + + Symbian Signed offers the following signing options depending on the + capabilities that the application accesses: + + \list + + \o \bold{Express signed} for applications that access only user and system + capabilities. + + \o \bold{Certified signed} for applications that access also restricted or + device manufacturer capabilities. + + \note You need to request the rights to access device manufacturer + capabilities from the manufacturer. + + \endlist + + For more information about how to choose the appropriate signing option and + how you can check which capabilities you need, see + \l{https://www.symbiansigned.com}{Symbian Signed} + and + \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}. + + For more information on how to define capabilities for a project, see + \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}. + + \note In Qt 4.7.1 and later, if you select the \gui {Self-signed certificate} + option, the SIS generation process checks that the package can be self-signed. + If problems are found, it attempts to fix the package. If fixes cannot be made, + a message appears in the \gui {Compile Output} view. + + The following modifications can be made: + + \list + + \o Package UID is changed to an UID from the unprotected range (if it was + from the protected range). + + \o Vendor ID is set to zero on all binaries included in the package file. + + \o All restricted and device manufacturer capabilities are removed from all + libraries included in the package file. + + \endlist + + The application UID or capabilities used in executables (.exe) cannot be changed, + because that would break the application. If the executables use protected UIDs + or restricted or device manufacturer capabilities, signing fails and an error + message appears in the \gui {Compile Output} view. + + \section1 Creating Smart Installer for Symbian Packages + + You can run Qt applications on Symbian devices if the software that Qt + applications require (typically Qt, Qt Mobility, QtWebkit, and Open C) is + installed on the device. On Symbian^3 and later devices, some version of Qt + is pre-installed. On earlier devices, you must install the modules that Qt + applications require. Nokia Smart Installer for Symbian makes it easier + for users to install Qt applications to Symbian phones by checking whether the device contains + the necessary software and by installing the missing pieces. + + For this to work, the Nokia Smart Installer must be packaged with the Qt application. The + application SIS file must first be Symbian Signed or signed by the Application + Signing Services for Ovi Store. The capabilities used in the applications + determine, which signing option must be selected. The wrapper package must be signed using + either the same option or a more extensive option than the application SIS. + + \note If you use the Application Signing Services for Ovi Store, you can submit an unsigned + wrapper package to Ovi Publishing. For more information, see + \l{Publishing Applications to Ovi Store}. + + You can either install the Nokia Smart Installer for Symbian as part of + the \QSDK, or download and install it from the + \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian} + wiki. + + To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer + package} check box. This ensures that up-to-date and appropriate versions of Qt and its + dependencies are installed on devices. Further, it reduces the file size of the application you + publish, because you do not have to deliver the required libraries. + + Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian: + + \list + + \o 0xA000D7CE for self-signed applications + \o 0x2002CCCF for Ovi Store or Symbian Signed packages + + \endlist + + \section2 Creating Self-signed Smart Installer Packages + + To create a self-signed Nokia Smart Installer for Symbian wrapped .sis file, + you must use an UID from the unprotected UID range, provided by Symbian Signed + and the wrapper package UID value 0xA000D7CE. If you used the \QC project + wizard to create the project, this wrapper package UID is used by default. + + \list 1 + + \o Make sure that the source directory is clean. For example, if you use Git, + enter the following command: + + \c {git clean -dfx} + + \o Click \gui Projects to edit the \gui {Build Settings} for the + \gui {Symbian Device} target. + + \o Select the \gui Release configuration. + + \o Open the \gui {Run Settings}. + + \o In the \gui {Create SIS Package} step, select \gui {Self-signed certificate}. + + \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to + skip the step of copying the SIS file to a device. The SIS file is created + in the project folder. + + \image qtcreator-remove-deploy-step.png "Removing deploy steps" + + \o To package Nokia Smart Installer for Symbian with the application, select + the \gui {Create Smart Installer package} check box. + + \o Edit the project .pro file to use the correct UIDs for the application and + the wrapper package, as illustrated by the following code snippet: + + \code + symbian { + TARGET.UID3 = 0xE4DE5D27 + DEPLOYMENT.installer_header=0xA000D7CE + + vendorinfo = \ + "%{\"CustomVendor-EN\"}" \ + ":\"CustomVendor\"" + + my_deployment.pkg_prerules = vendorinfo + DEPLOYMENT += my_deployment + } + \endcode + + \o Choose \gui {Build > Run Project}. + + \endlist + + \QC automatically generates a wrapper package in the project folder. + + \section2 Creating Symbian Signed Smart Installer Packages + + If the application uses functions that require advanced capabilities (AllFiles, + DRM, TCB, CommDD, DiskAdmin, NetworkControl, MultimediaDD), you must use the + standard Symbian Signed process to have the application Symbian Signed. Depending + on the capabilities used, you may use either the Express Signed or the Certified + Signed path, or the manufacturer-specific channel (for AllFiles, DRM, and TCB). + + \list 1 + + \o Make sure that the source directory is clean. For example, if you use Git, + enter the following command: + + \c {git clean -dfx} + + \o Click \gui Projects to edit the \gui {Build Settings} for the + \gui {Symbian Device} target. + + \o Select the \gui Release configuration. + + \o Open the \gui {Run Settings}. + + \o In the \gui {Create SIS Package} step, specify the developer certificate + and key in the \gui {Custom certificate} and \gui {Key file} fields. + + \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to + skip the step of copying the SIS file to a device. The SIS file is created + in the project folder. + + \o Edit the project .pro file to use the correct UIDs and vendor information + for the application, as illustrated by the following code snippet: + + \code + symbian { + TARGET.UID3 = 0x2000D7D1 + DEPLOYMENT.installer_header=0x2002CCCF + + vendorinfo = \ + "%{\"CustomVendor-EN\"}" \ + ":\"CustomVendor\"" + + my_deployment.pkg_prerules = vendorinfo + DEPLOYMENT += my_deployment + } + \endcode + + \o Choose \gui {Build > Run Project}. + + \o Submit the created .sis file to Symbian Signed for certification. + + \note Ensure that your application complies with the Symbian Signed + Test Criteria before submitting the file for certification. Also, if the file is + intended for Ovi Store publishing, verify that the application complies with Ovi + Store publishing requirements. + + \o After receiving the .sis file from Symbian Signed, copy it over the old + application.sis. + + \note The instructions below assume that you have installed \QSDK. + + \o To package Nokia Smart Installer for Symbian with the application, choose + \gui {Start > Qt SDK > Symbian > Qt for Symbian Command Prompt} + to open the Qt command line environment. + + \o Change to the project directory. For example: + + \c{cd C:\Sources\Application} + + \o To create a Smart Installer wrapper package, enter the following + command: + + \c {C:\Sources\Application> make ok_installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key} + + \o Submit the created wrapped .sis file, application_installer.sis, to + Symbian Signed. Express Signed is a suitable signing option for the wrapper + package. The capabilities used in the application do not play a role here, + because the wrapper package is already signed. + + \endlist + + \QC automatically generates a wrapper package in the project folder. + + \note Ensure that your application complies with the requirements before submitting + the file to Ovi Store. + + For more information about the qmake DEPLOYMENT variable, see + \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#deployment}{qmake Variable Reference}. + + For more information about the Nokia Smart Installer, see the + \l{http://doc.qt.nokia.com/smart-installer/index.html}{Nokia Smart Installer for Symbian Manual}. + + Note: Nokia Smart Installer for Symbian is only available on Windows. + + \section1 Application UID + + A UID is a globally unique identifier that is used to + uniquely identify, for example, an object or file type. In Symbian development, + objects are identified by compound identifiers that are constructed from three + UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an + object, whereas UID3 identifies a particular object, such as an application. + + When you create a \gui {Mobile Qt Application}, \QC adds a UID3 suitable for + development and debugging automatically to the application .pro file. However, to + distribute your application and get it Symbian Signed, you must apply for a UID + from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one + at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed} + web site. + + If you use the Ovi Signed process, Ovi Publisher Support allocates the UID for you. + + Replace the testing UID with the distribution UID in the .pro file before you + build the final installation package. For more information, see + \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}. + +*/ diff --git a/doc/src/symbian/creator-faq-debug-output-symbian.qdocinc b/doc/src/symbian/creator-faq-debug-output-symbian.qdocinc new file mode 100644 index 00000000000..5289b90e127 --- /dev/null +++ b/doc/src/symbian/creator-faq-debug-output-symbian.qdocinc @@ -0,0 +1,13 @@ + \bold {On Symbian OS}: \c qDebug() and related functions use the native + \c RDebug::Print functionality. + + When you use the Symbian emulator on Windows, the output is redirected to + standard debug output. To view it, you can use a Windows debug output + viewer, such as the DebugView for Windows. + + On devices, the \c RDebug output is intercepted by \e CODA or \e {App TRK} + and then propagated to \QC, which displays it in the + \gui {Application Output} pane. + + Symbian OS provides no support for differentiating between standard output + and error output. diff --git a/doc/src/symbian/creator-projects-building-symbian.qdocinc b/doc/src/symbian/creator-projects-building-symbian.qdocinc new file mode 100644 index 00000000000..b8b2f7cb8fe --- /dev/null +++ b/doc/src/symbian/creator-projects-building-symbian.qdocinc @@ -0,0 +1,25 @@ + \section1 Building for Symbian + + The tool chain for building applications locally on the development PC for + the \gui {Symbian Device} target is only supported on Windows. + If you develop on Linux or Mac OS, you must use the Remote Compiler + interface to a compilation service at Nokia Developer. For more information, + see \l{Building with Remote Compiler}. + + \section2 Troubleshooting Build Issues + + If you cannot build the application for a Symbian device, check that: + + \list + + \o You selected the Symbian Device target to build the application. + + \o You selected the correct Qt version to build the application. + For more information, see \l{Selecting Qt for Symbian Versions}. + + \endlist + + \section1 Building for Symbian Emulator + + \QC does not create release configurations for the \gui {Symbian Emulator} + target, because Symbian Emulator supports only debug builds. diff --git a/doc/src/symbian/creator-projects-qt-versions-symbian.qdocinc b/doc/src/symbian/creator-projects-qt-versions-symbian.qdocinc new file mode 100644 index 00000000000..32a31303d28 --- /dev/null +++ b/doc/src/symbian/creator-projects-qt-versions-symbian.qdocinc @@ -0,0 +1,32 @@ + \section2 Setting Up Qt for Symbian Versions + + If you install Qt for Symbian as a part of \QSDK, it is automatically + detected by \QC. If you install other Symbian SDKs and register them + with devices.exe, \QC automatically detects the Qt version. + + If the selected Qt version was built using the SBSv2 build system, that + is available for Symbian OS 9.5 based SDKs, \QC builds your projects + using this build system. The \gui {SBS v2 directory} field is enabled and + you must specify the path to the directory where the SBS executable (for + example, sbs.bat on Windows) is located. + + To add a Qt for Symbian version: + + \list 1 + + \o Select \gui Tools > \gui Options > \gui Qt4 > \gui{Qt Versions}. + + \o Select the Qt for Symbian version you want the \QC to use. + + \image qtcreator-qt4-qtversions-win-symbian.png + + For more information about how to add tool chains for using the + GCCE and WINSCW compilers, see \l{Adding Tool Chains}. + + \o In the \gui {S60 SDK} field, enter the path to the directory where + the Symbian SDK is located. + + \o In the \gui {SBS v2 directory} field, enter the path to the + directory where the SBS v2 executable is located. + + \endlist diff --git a/doc/src/symbian/creator-projects-running-symbian.qdocinc b/doc/src/symbian/creator-projects-running-symbian.qdocinc new file mode 100644 index 00000000000..1988e03b1f6 --- /dev/null +++ b/doc/src/symbian/creator-projects-running-symbian.qdocinc @@ -0,0 +1,96 @@ + \section1 Running on Symbian + + \list 1 + + \o Build and run the application for \l{Running on Qt Simulator} + {Qt Simulator}. + + \o If no problems are found, build and run the application for a + device. + + \o To test functionality that uses Symbian APIs, you can build and + run the application for Symbian Emulator. + + \endlist + + \section2 Running on a Device + + \list 1 + + \o Install the required software on the device. For more information, + see \l{Connecting Symbian Devices}. + + \o Connect the device to the development PC through a USB cable. + The target selector displays a green check mark when a device is + connected. + + \image qtcreator-qt4-symbian-device-connected.png + + The tool tip of the target selector shows more details about the + actual device that will be used when you run your application. + + \o Start the CODA debugging agent on the device. + + \note If you use CODA over an USB connection, it starts up + automatically when you connect the device to the development PC. + + \o Click the \gui Run button. + + \endlist + + You can connect several devices to your development PC simultaneously. + In the details of the run configuration for the \gui{Symbian Device} target, + select the device to run your application on. + + When your application is ready for delivery to users, specify run settings + for creating the final SIS installation packages. For more information, + see \l{Creating SIS Files}. + + If you cannot run the application on a device, check that: + + \list + + \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite} + have been installed on the development PC. + + \o The device is connected through USB cable in \e{PC Suite} mode. + + \o The CODA debugging agent is installed on the device and it is + running with the status \e connected. + + \note If you use the CODA debugging agent over WLAN, you must enter + the WLAN address and port number in \QC, separated by a colon (:). + For example: 192.167.0.100:1534 + + \o The device is detected and selected in the \gui {Run Settings}. + + \endlist + + If this does not help to solve your problem, search the + qt-creator@trolltech.com mailing list archives or provide feedback to us via + the methods described on the + \l{http://developer.qt.nokia.com/wiki/Category:Tools::QtCreator} + {\QC Development Wiki}. + + \section2 Running on Symbian Emulator + + Select the \gui{Symbian Emulator} target as the active one, and build and + run your project. + + If you cannot run the application in the emulator, check that: + + \list + + \o You selected the \gui{Symbian Emulator} target for your application. + + \o If you cannot select \gui {Symbian Emulator} as target, check that + Carbide.c++ is installed correctly and that the path to the + Carbide.c++ installation directory is specified for the WINSCW tool + chain in the \gui{Compiler path} field in \gui {Tools > Options > + Tool Chains}. + + \o If the emulator process cannot be started, try closing \QC and + starting the application directly from your file manager. Having + done this, \QC should be able to run your projects in the emulator. + + \endlist diff --git a/doc/src/symbian/creator-projects-settings-run-symbian.qdocinc b/doc/src/symbian/creator-projects-settings-run-symbian.qdocinc new file mode 100644 index 00000000000..662115015a6 --- /dev/null +++ b/doc/src/symbian/creator-projects-settings-run-symbian.qdocinc @@ -0,0 +1,31 @@ + \section2 Specifying Run Settings for Symbian Devices + + \QC automatically detects Symbian devices that are connected to the + development PC with a USB cable. If only one device is detected, the + application is deployed to it and run on it. If multiple devices are + connected to the PC, make sure that the correct device is selected in the + \gui {Symbian Device} run settings for your project. + + You can also pass command line arguments to your application on the device. + Press the \gui{Device info button} to get more information about the + selected device, such as the CPU type and the running debugging agent + version. + + \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices" + + To use the CODA debugging agent over a WLAN connection, enter the WLAN + address of the device and the port number to use, separated by a colon (:), + in the \gui WLAN field. For example: 192.167.0.100:1534 + + When you deploy the application for the \gui{Symbian Device} target, \QC + generates a Symbian installation system (SIS) file in the project folder + and copies it to the device that is connected to the development PC. If no + device is connected, you must remove the \gui {Deploy SIS Package} step, + to create the package. Click \gui {Remove Item} to skip the step. + + \image qtcreator-remove-deploy-step.png "Removing deploy steps" + + When you are ready to publish the application on Ovi Store or some other + channel, you must make sure that the SIS file meets the requirements for + publishing and installing applications on Symbian devices. For more + information, see \l{Deploying Applications to Symbian Devices}. diff --git a/doc/src/symbian/creator-publish-ovi-symbian.qdoc b/doc/src/symbian/creator-publish-ovi-symbian.qdoc new file mode 100644 index 00000000000..253040e9de4 --- /dev/null +++ b/doc/src/symbian/creator-publish-ovi-symbian.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// 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-publish-ovi.html + \page creator-publish-ovi-symbian.html + \nextpage creator-publish-ovi-maemo.html + + \title Publishing Qt Content for Symbian Devices + + You can use the \e {Application Signing Services for Ovi Store} to get your + application Express Signed for free by Nokia. Make sure to use the + \l{Application UID}{application UID} that you receive from Ovi Publisher + Support. + + The \gui {Publish Qt Symbian Applications to Ovi Store} wizard allows you + to check that your application can be published on Ovi Store. It checks that + the application UID, vendor name, and the capabilities used meet the Ovi + Publishing criteria. + + If you use Symbian Signed UIDs or the application uses functions that + require advanced \l{Capabilities and Signing}{capabilities}, you must use + the standard Symbian Signed process to have the application Symbian Signed + (using the Certified Signed path or the manufacturer-specific channel). + For more information, see \l{Deploying Applications to Symbian Devices}. + + To use the publishing wizard: + + \list 1 + + \o Select \gui Projects to select the Qt version to build the + application. For more information, see + \l{Selecting Qt for Symbian Versions}. + + \o Select the \gui {Symbian Device} build target for your project. + + \o Choose \gui {Build > Publish Project}. + + \o Select \gui {Publish Qt Symbian Applications to Ovi Store}, and then + select \gui {Start Wizard}. + + \o Select the Qt version and device type to build against and click + \gui Next. We recommend that you select a release configuration. + + \o The wizard checks the information in the project file against the + Ovi Publishing criteria and indicates possible problems. You can fix + some of the problems in the wizard. + + \image qtcreator-publishing-wizard-symbian.png "Project File Checks dialog" + + \o Select \gui Commit to save changes and create the .sis file. The + .sis file is packaged with Nokia Smart Installer for Symbian. + + \o Choose \gui {Open Containing Folder} to open the folder where the + .sis file was created. + + \o Submit the created .sis file to Ovi Publishing as a Qt Content item. + + \note You cannot use this .sis file for testing. + + \endlist + + \note After you change the application UID, you must use the developer + certificate-key pair that you receive from Ovi Publisher Support for testing + the application on devices. The following error message is displayed on the + device if you use UIDs from the trusted range (0x2xxxxxxx) in a self-signed + application: \gui {Unable to install a trusted application from a trusted + supplier.} For more + information, see \l{http://www.developer.nokia.com/Community/Wiki/UID}{UID}. + + If you try to use more capabilites than the certificate permits, the + following error message is displayed on the device: \gui {Requested + application access not granted.} For example, if you try to install a + self-signed application that uses a system capability. + +*/ diff --git a/doc/src/symbian/qtquick-components-symbian.qdoc b/doc/src/symbian/qtquick-components-symbian.qdoc new file mode 100644 index 00000000000..93356939ec8 --- /dev/null +++ b/doc/src/symbian/qtquick-components-symbian.qdoc @@ -0,0 +1,241 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// 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-qml-application.html + \page creator-qml-components-example.html + \nextpage creator-writing-program.html + + \title Creating a Qt Quick Application Using Qt Quick Components + + \note To complete this tutorial, you must install the Qt Quick Components + for Symbian and the Symbian^3 tool chain as part of the \QSDK. In addition, + you must install the Qt Quick Components on the test device. + + This tutorial describes how to use Qt Creator to create a small Qt + application, Battery Status, that uses the System Information + Mobility API to fetch battery information from the device. + + \image qtcreator-symbian-components-example.png "Mobile example" + + The user interface for the application is designed using Qt Quick Components + for Symbian. This enforces a platform look and feel for Symbian^3 devices. + + \section1 Creating the Project + + \list 1 + + \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick + Application > Choose}. + + \o In the \gui{Name} field, type \bold {BatteryStatus}. + + \o In the \gui {Create in} field, enter the path for the project files. + For example, \c {C:\Qt\examples}, and then click \gui{Next}. + + \o In the \gui {Application Type} dialog, select \gui {Qt Quick + Components (Symbian Applications)}, and then click \gui{Next}. + + \o Select \gui {Symbian Device} and \gui {Qt Simulator} targets, and + then click \gui{Next}. + + \note Targets are listed if you installed the appropriate + development environment, for example, as part of the \QSDK. You can + add targets later in the \gui Projects mode. + + \o Select \gui Next in the following dialogs to use the default + settings. + + \note Qt Creator contains a default program icon and generates an + \l{Application UID}, for testing the application on a device. You + only need to change the icon and UID if you deliver the application + for public use. + + \o Review the project settings, and click \gui{Finish} to create the + project. + + \endlist + + Qt Creator generates the necessary files that contain boiler plate code. The + wizard creates an application that uses + \l{http://doc.qt.nokia.com/qt-components-symbian-1.0/qt-components-pages-and-navigation-overview.html} + {page-based application navigation}. + + Modify the files as described in the following sections. + + \section1 Declaring the Qt Mobility API + + To use the Qt Mobility APIs or develop applications for Symbian devices, + you must modify the .pro file to declare the Qt Mobility APIs that you use. + + This example uses the System Info API, so you must declare it, as + illustrated by the following code snippet: + + \code + + CONFIG += mobility + MOBILITY = systeminfo + + \endcode + + Each Mobility API has its corresponding value that you have to add + as a value of MOBILITY to use the API. For a list of the APIs and the + corresponding values that you can assign to MOBILITY, see the + \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}. + + \section1 Adding Import Statements + + The wizard adds the import statements for Qt Quick and the Qt Quick + Components for Symbian to the MainPage.qml file: + + \code + import QtQuick 1.0 + import com.nokia.symbian 1.0 + \endcode + + To use the Qt Mobility APIs, you must add the import statements for the + Qt Mobility APIs that you use. This example uses the System Info API, so you + must import it, as illustrated by the following code snippet: + + \code + import QtMobility.systeminfo 1.1 + \endcode + + Use the values as you can assign to MOBILITY also to construct import + statements. + + \section1 Creating the Main View + + Qt Creator generates a default QML file that you can modify to create the + main view of the application. It displays a progress bar and a text label + that indicate the battery status. + + \list 1 + + \o Click \gui Design to open MainPage.qml in \QMLD. + + \o In the \gui Navigator pane, select the \gui Text element to edit its + properties in the \gui Properties pane. + + \o In the \gui Text field, change the text from \bold {Hello World!} + to \gui {Battery status: 1%}. + + \o In the \gui Library view, \gui Items tab, select the + \gui ProgressBar element, drag and drop it to the canvas, and edit + its properties. + + \image qtcreator-symbian-components-example-ui.png "Qt Quick Components for Symbian" + + \list 1 + + \o Click \gui {Layout}, and then click the top anchor button. + + \o In the \gui Target field, select \gui text1, to anchor the + progress bar to the bottom of the text field. + + \o In the \gui Margin field, select 20. + + \o Click the horizontal anchor button, and select \gui text1 in + the \gui Target field to anchor the progress bar + horizontally to the text field. + + \o To check that the application can be built and run, select + \gui {Qt Simulator} as the target and click the + \inlineimage qtcreator-run.png + button. + + \endlist + + \endlist + + \section1 Fetching Battery Status + + To fetch the battery status, open MainPage.qml in the code editor and add + some code to it: + + \list 1 + + \o Add an invisible + \l{http://doc.qt.nokia.com/qtmobility/qml-deviceinfo.html} + {DeviceInfo element} that contains two signals. The + \l{http://doc.qt.nokia.com/4.7/qml-component.html#onCompleted-signal} + {onCompleted} signal starts battery level notification when the + component is initialized. The + \l{http://doc.qt.nokia.com/qtmobility/qml-deviceinfo.html#batteryLevelChanged-signal} + {batteryLevelChanged} signal is called when the battery level + changes. + + \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 0 + + \o Set an expression as the value of the text property of the Text + element to display the battery level as a percentage: + + \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 1 + + \o Set values for the ProgressBar element to display the battery level + on the progress bar: + + \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 2 + + \endlist + + + \section1 Compiling and Running Your Program + + Now that you have all the necessary code, select \gui {Qt Simulator} + as the target and click the + \inlineimage qtcreator-run.png + button to build your program and run it in the Qt Simulator. + + In Qt Simulator, run the runOutOfBattery.qs example script to see the value + change in the Battery Status application. Select \gui {Scripting > examples + > runOutOfBattery.qs > Run Selected Script}. + + \image qtcreator-symbian-components-example-simulated.png "Mobile example in Qt Simulator" + + \section1 Testing on a Symbian Device + + You also need to test the application on real devices. Before you can + start testing on Symbian devices, you must connect them to the development + PC by using a USB cable and install the necessary software on them. + + \list 1 + + \o Install Qt libraries, Qt mobile libraries, Qt Quick components for + Symbian, and a debugging agent on the device. For more information, + see \l{Connecting Symbian Devices}. + + \o Start the CODA debugging agent on the device. + + \o Click the \gui {Target Selector} and select \gui {Symbian Device}. + + \o Click \gui Run to build the application for the Symbian device. + + \endlist + +*/ diff --git a/doc/symbiandev.qdoc b/doc/src/symbian/symbiandev.qdoc similarity index 59% rename from doc/symbiandev.qdoc rename to doc/src/symbian/symbiandev.qdoc index 43e50641ce6..b62777923a0 100644 --- a/doc/symbiandev.qdoc +++ b/doc/src/symbian/symbiandev.qdoc @@ -36,40 +36,31 @@ \title Connecting Symbian Devices When you install \QSDK, the build and run settings for Symbian devices - are set up automatically in Qt Creator. You only need to install and launch + are set up automatically in \QC. You only need to install and launch the CODA on-device debugging agent on the devices and connect the devices to the development PC. Make sure that PC Suite or Ovi Suite are installed on the development PC. Connect the device to the development PC with an USB cable in - PC Suite Mode. If you have not previously used the device with Ovi Suite + PC Suite or Ovi Suite Mode. If you have not previously used the device with + Ovi Suite or PC Suite, all the necessary drivers are installed automatically. This takes approximately one minute. - As with every supported platform, Qt strives to maintain application - behavior and binary compatibility throughout the lifetime of the Qt 4.x - major version and on the Symbian devices that support Qt. Symbian - support in \QSDK and Ovi Store were introduced with Qt 4.6. Each Qt release - contains bug fixes that might change the API behavior and thereby affect - application compatibility. - - In addition, Symbian devices have different input methods, such as different - keyboard styles or touch input, screen sizes, memory, and CPU and GPU - capabilities. Therefore, you must test applications on specific target - devices to ensure compatibility. In order to build applications that are - supported also on earlier devices, select the target in \QSDK carefully. - Generally, an earlier target (such as S60 5th Edition) is supported on a - larger number of devices than a later target (such as Symbian Belle). - You can run Qt applications on Symbian devices if the software that Qt applications require (typically Qt, Qt Mobility, QtWebkit, and Open C) is installed on the device. On Symbian^3 and later devices, some version of Qt is pre-installed. To deploy applications to earlier devices, you can package the application with Nokia Smart Installer for Symbian to automatically - install the modules that Qt applications require. For more information, see - \l{Qt on Symbian Devices}. + install the modules that Qt applications require. For more information about + which Qt modules are supported on-demand for different Symbian device + models, see + \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian} + {Nokia Smart Installer for Symbian}. - To run and debug applications on Symbian devices from Qt Creator, you must + + + To run and debug applications on Symbian devices from \QC, you must install the CODA on-device debugging agent on the device. For more information, see \if defined(qcmanual) @@ -103,164 +94,10 @@ to install Carbide.c++ v2.0.0 or higher. \endif - - \section1 Qt on Symbian Devices - - Generally, when developing for Symbian^3 or later devices, you do not need - to install Qt on devices. However, you might want to upgrade or downgrade - the Qt version on a device to test your application on a particular Qt - version. Use the installation packages delivered with \QSDK - (\c {\Symbian\sis}). Keep in mind that this might - replace the pre-installed Qt on the device. - - \note Earlier Qt for Symbian versions, such as Qt 4.6.3 for Symbian, are - only available in the \QSDK online installer. For more information, see - \if defined(qcmanual) - \l{http://doc.qt.nokia.com/sdk/sdk-installing.html}{Installing Qt SDK}. - \else - \l{Installing Qt SDK}. - \endif - - - Qt is supported on different Symbian platforms as follows: - - \list - - \o Symbian Belle devices contain Qt 4.7.4 and Qt Mobility 1.2.1 - libraries as part of device - firmware (ROM). To upgrade the Qt version, update the device - firmware. You cannot downgrade the Qt version on Belle devices. - - \omit - To develop applications using Qt 4.8 or later, you can install Qt - 4.8 or later libraries to Belle devices. The Qt in Belle firmware is - not overwritten. It is eclipsed by the installed Qt on the C: drive. - \endomit - - \o Symbian Anna devices have Qt 4.7.3 and Qt Mobility 1.1.3 - pre-installed. - - \o Symbian^3 devices have Qt 4.6.3 pre-installed, but they do not have - Qt Mobility libraries pre-installed. If you use Qt Mobility features - in your application, package the application with Nokia Smart - Installer for Symbian to have the necessary dependencies installed - automatically. - - \o Symbian^1 (S60 5th Edition) devices support Qt 4.6.3 and 4.7.3, but - it is not pre-installed to them. Package Qt applications with Nokia Smart - Installer for Symbian to have the latest Qt and Qt Mobility versions - that the device supports installed to the device. - - \note As an exception, the Nokia C6-00 PR4 has Qt 4.7.3 and Qt - Mobility 1.1.3 preinstalled. - - \o S60 3rd Edition feature pack 1 and later devices support Qt 4.6, but - it is not pre-installed to them. Package Qt applications with Nokia - Smart Installer for Symbian. - - \endlist - - To check the Symbian platform version of your device, see - \l{http://www.developer.nokia.com/Devices/Device_specifications/} - {Device Specifications}. The site contains information about the content - that can be published for the device to the Ovi Store (\e General section) - and the Qt libraries that are pre-installed on the device (\e API section). - - If the device does not have the necessary Qt libraries pre-installed, you - can use Nokia Smart Installer for Symbian to deploy them during application - installation. Smart Installer ensures that the necessary libraries are - available in the target Symbian device before installing the actual - application. For more information about which Qt modules are supported - on-demand for different Symbian device models and how to enable Smart - Installer support in Qt applications, see - \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian}. - - \section2 Selecting Qt Versions in Qt Creator - - When you select the Qt version to build the application with, consider - which version provides the application with the widest support on different - Symbian platforms. The binary compatibility promise of Qt and Symbian means - that applications that are built against Qt 4.6.3 also run on Qt 4.7.3. - Similarly, applications that are supported on S60 5th Edition are also - supported - on Symbian^3. However, dependencies, such as Qt Quick or Qt Mobility API - versions might restrict the choice of Qt versions that you have. - - In general, if you use only Qt 4.6 APIs in the application, you - can use \gui {Qt 4.6.3 for Symbian^1} to build it. - The application is supported on both Symbian^1 and Symbian^3 devices. - - If you use Qt Quick in the application, you can use \gui {Qt 4.7.3 for - Symbian^1} to build it. The application is supported on both Symbian^1 and - Symbian^3 devices. - - If you use native Symbian APIs, you must check that they are available on - the target devices. For more information about the API differences between - Symbian^1 and Symbian^3, see the \bold {Symbian - Reference Documentation for Qt}, which is delivered together with \QSDK - and which you can view in the \gui Help mode. - - You can use a set of ready-made UI components called Qt Quick Components - for Symbian that enforce a Nokia UI look and feel. - \omit - \note We recomment that you use Qt Quick Components version 1.1, because - they contain usability and other improvements. The same set of devices - supports both 1.0 and 1.1. - \endomit - - The following table summarizes the supported configurations for each Qt - version available in Qt Creator build settings: - - \table - \header - \i Qt Version - \i Qt Quick - \i Qt Quick Components - \i Qt Mobility Version - \i Native Symbian C++ APIs - \i Open GL - \row - \i Qt 4.6.3 for Symbian^1 (S60 5th Edition) - \i No - \i No - \i 1.0.2 - \i No - \i No - \row - \i Qt 4.6.3 for Symbian^3 - \i No - \i No - \i 1.0.2 - \i Yes - \i No - \row - \i Qt 4.7.3 for Symbian^1 - \i 1.0 - \i No - \i 1.1.3 - \i No - \i No - \row - \i Qt 4.7.3 for Symbian^3 - \i 1.0 - \i Yes \omit 1.0 \endomit - \i 1.1.3 - \i Yes - \i Yes - \row - \i Qt 4.7.4 for Symbian Belle - \i 1.1 - \i Yes \omit 1.1 \endomit - \i 1.2.1 - \i Yes - \i Yes - \endtable - - \if defined(qcmanual) \section1 Using On-device Debugging Agents Support for the App TRK on-device debugging agent has been removed from - Qt Creator 2.3. Only CODA is supported. It offers the following benefits: + \QC 2.3. Only CODA is supported. It offers the following benefits: \list @@ -285,11 +122,11 @@ \section1 Setting Up Qt Creator - When you run Qt Creator after installing the Symbian SDK and Qt for + When you run \QC after installing the Symbian SDK and Qt for Symbian, the installed SDKs and their corresponding Qt versions are automatically detected. For each detected Symbian SDK with Qt, a special entry is made in the Qt version management settings in \gui{Tools} > - \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. + \gui{Options} > \gui{Qt4} > \gui{Qt Versions}. If you manually add a Qt version for Symbian, you must also manually specify the Symbian SDK to use for this version. @@ -297,12 +134,10 @@ For more information about adding Qt versions and tool chains, see \l{Setting Up Qt for Symbian Versions} and \l{Adding Tool Chains}. - \else - \section1 Building and Running Applications You can test your application on a device by building and running - it from Qt Creator for the \gui {Symbian Device} target. + it from \QC for the \gui {Symbian Device} target. \list 1 @@ -319,10 +154,98 @@ \o Select \gui Options to select USB as connection type. - \o Click the \gui Run button in Qt Creator. + \o Click \gui Projects to edit the \gui {Build Settings} for the + \gui {Symbian Device} target. Select the Qt version to use for building + the application. For more information, see + \l{Selecting Qt for Symbian Versions}. + + \o Click the \gui Run button in \QC. \endlist - \endif + \section2 Selecting Qt for Symbian Versions + + When you select the Qt for Symbian version to build the application with, consider + which version provides the application with the widest support on different + Symbian platforms. The binary compatibility promise of Qt and Symbian means + that applications that are built against Qt 4.6.3 also run on Qt 4.7.3. + Similarly, applications that are supported on S60 5th Edition are also + supported + on Symbian^3. However, dependencies, such as Qt Quick or Qt Mobility API + versions might restrict the choice of Qt versions that you have. + + In general, if you use only Qt 4.6 APIs in the application, you + can use \gui {Qt 4.6.3 for Symbian^1} to build it. + The application is supported on both Symbian^1 and Symbian^3 devices. + + If you use Qt Quick in the application, you can use \gui {Qt 4.7.3 for + Symbian^1} to build it. The application is supported on both Symbian^1 and + Symbian^3 devices. + + \note The tool chains for developing applications for S60 3rd Edition + devices have been removed from \QSDK 1.1. To develop for these early + devices, use an earlier version of \QSDK. + + If you use native Symbian APIs, you must check that they are available on + the target devices. For more information about the API differences between + Symbian platforms, see the \bold {Symbian + Reference Documentation for Qt}, which is delivered together with \QSDK + and which you can view in the \gui Help mode. + + You can use a set of ready-made UI components called Qt Quick Components + for Symbian that enforce a Nokia UI look and feel. + \omit + \note We recomment that you use Qt Quick Components version 1.1, because + they contain usability and other improvements. The same set of devices + supports both 1.0 and 1.1. + \endomit + + The following table summarizes the supported configurations for each Qt + version available in \QC build settings: + + \table + \header + \i Qt Version + \i Qt Quick + \i Qt Quick Components + \i Qt Mobility Version + \i Native Symbian C++ APIs + \i OpenGL + \row + \i Qt 4.6.3 for Symbian^1 (S60 5th Edition) + \i No + \i No + \i 1.0.2 + \i No + \i No + \row + \i Qt 4.6.3 for Symbian^3 + \i No + \i No + \i 1.0.2 + \i Yes + \i No + \row + \i Qt 4.7.3 for Symbian^1 + \i 1.0 + \i No + \i 1.1.3 + \i No + \i No + \row + \i Qt 4.7.3 for Symbian^3 and Symbian Anna + \i 1.0 + \i Yes \omit 1.0 \endomit + \i 1.1.3 + \i Yes + \i Yes + \row + \i Qt 4.7.4 for Symbian Belle + \i 1.1 + \i Yes \omit 1.1 \endomit + \i 1.2 + \i Yes + \i Yes + \endtable */