feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: move info about Symbian target to a separate folder

Browse Source 
Change-Id: I93db9d03057f9f80a041447f41eefe98f8b4c41c
Reviewed-on: http://codereview.qt-project.org/5613
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Eike Ziller <eike.ziller@nokia.com>
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
This commit is contained in:
Leena Miettinen
2011-09-27 11:58:46 +02:00
parent a91ba2b311
commit c9f0988eee
9 changed files with 1016 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
doc/src/symbian/creator-deployment-symbian.qdoc Normal file
View File

@@ -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}.
*/

13
doc/src/symbian/creator-faq-debug-output-symbian.qdocinc Normal file
View File

@@ -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.

25
doc/src/symbian/creator-projects-building-symbian.qdocinc Normal file
View File

@@ -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.

32
doc/src/symbian/creator-projects-qt-versions-symbian.qdocinc Normal file
View File

@@ -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

96
doc/src/symbian/creator-projects-running-symbian.qdocinc Normal file
View File

@@ -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

31
doc/src/symbian/creator-projects-settings-run-symbian.qdocinc Normal file
View File

@@ -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}.

101
doc/src/symbian/creator-publish-ovi-symbian.qdoc Normal file
View File

@@ -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.
*/

241
doc/src/symbian/qtquick-components-symbian.qdoc Normal file
View File

@@ -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
*/

287
doc/symbiandev.qdoc → doc/src/symbian/symbiandev.qdoc
View File

@@ -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 {<QtSDK_install_path>\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
*/