1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\group platform-specific
\title Platform-Specific Documentation
\brief Documents describing platform-specific features of Qt.
These documents describe platform-specific features provided by Qt, and
discuss issues related to particular platforms and environments.
\generatelist{related}
*/
/*!
\page platform-notes.html
\ingroup platform-specific
\title Platform and Compiler Notes
\brief Information about the platforms on which Qt can be used.
This page contains information about the platforms Qt is currently known
to run on, with links to platform-specific notes, including any known bugs
or incompatibilities.
Information about the combinations of platforms and compilers
supported by Qt can be found on the \l{Supported Platforms} page.
\list
\o \l{Platform and Compiler Notes - Symbian}
\tableofcontents{1 Platform and Compiler Notes - Symbian}
\endlist
*/
/*!
\page platform-notes-symbian.html
\title Platform and Compiler Notes - Symbian
\contentspage Platform and Compiler Notes
\ingroup platform-specific
\brief Information about the state of support for the Symbian platform.
This page describes implementation details regarding the Qt for Symbian port. To get
started with application development for Symbian devices, read the \l
{http://doc.qt.nokia.com/qtcreator/creator-developing-symbian.html}
{Connecting Symbian Devices} document.
\section1 Source Compatibility
Qt for Symbian provides the same level of source compatibility guarantee as
given for other platforms. That is, a program which compiles against a given
version of Qt for Symbian will also compile against all future versions of the
same major release.
\section1 Binary Compatibility
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 \l {Supported Devices}{Symbian devices that support Qt}.
Symbian support in Qt SDK 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 Qt SDK 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).
\target Supported Devices
\section1 Supported Devices
The \l {http://developer.qt.nokia.com/wiki/support_for_Symbian}{Support for Symbian} document
details the Qt support on different Symbian devices.
The \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian#Supported_Devices}
{Nokia Smart Installer for Symbian} document lists how Qt is supported on
different Symbian devices through Smart Installer.
Qt versions are supported by Symbian devices as follows:
\list
\o Qt 4.6 is supported by S60 3rd Edition feature pack 1 and newer devices
through \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Smart Installer}.
\o Qt 4.7.3 is supported by S60 5th Edition and newer devices
through \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Smart Installer}.
\endlist
Symbian devices have a pre-installed Qt support as follows:
\list
\o Symbian Anna: Qt 4.7.3 in C: drive. Note that Qt 4.7.4 is supported in Symbian Anna
through \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Smart Installer}.
\o Symbian Belle: Qt 4.7.4 in device firmware (ROM).
\endlist
\section1 Functionality Support
The following technologies and classes are not supported:
\list
\o QtConcurrent
\o QtDBus
\o \l {http://doc.qt.nokia.com/4.8/printing.html}{Printing support}
\o Qt3Support
\endlist
The following technologies have limited support:
\table
\header \o Module
\o Note
\row \o QtSql
\o The supported drivers are SQLite and QSYMSQL.
\row \o QtMultimedia
\o For support details see \l {Multimedia Support} section.
\row \o QtGui
\o QtGui's widgets are deprecated (i.e. they are available but not
recommended to use) in the Symbian port. It is recommended to use \l
{http://doc.qt.nokia.com/qt-components-symbian-1.1/symbian-components-functional.html}
{Qt Quick Components for Symbian} instead, because they provide
better look and feel on Symbian devices.
Moreover, the following classes of QtGui \bold {should not
be used} in a Symbian application:
\list
\o QFileDialog with the \c DontUseNativeDialog option
\o QColorDialog with the \c DontUseNativeDialog option
\o QFontDialog
\o QWizard
\o QCalendarWidget
\o QDateTimeEdit
\o QMdiArea
\o QDockWidget
\o QMdiSubWindow
\o QPrintPreviewWidget
\endlist
QScrollArea: The scrolling and focus handling of QScrollArea's all
scrollable widgets, for example QListView, differs from native Avkon
list widgets' one. Native Avkon scrollable components support
touch-gesture-based scrolling by dragging and flicking the UI
component but this functionality is not implemented in Qt widgets.
Scrolling by dragging and flicking works also in Qt Quick Components
that implements the \l
{http://www.developer.nokia.com/Resources/Library/Symbian_Design_Guidelines/}
{Symbian design guidelines}.
\endtable
\section1 Compiler Notes
For the application development the necessary compiler toolchain is included in \l
{http://qt.nokia.com/downloads}{Qt SDK}. For instructions compiling Qt
itself see the \l
{http://doc.qt.nokia.com/stable/install-symbian.html}
{Installing Qt for the Symbian platform} document.
\section1 Known Issues
Known issues can be found by visiting the
\l{http://qt.gitorious.org/qt/pages/QtKnownIssues}{wiki page} with an
up-to-date list of known issues, and the list of bugs can be found by
\l{http://bugreports.qt.nokia.com/browse/QTBUG/component/19171}{browsing} the
S60 component in Qt's public task tracker, located at
\l{http://bugreports.qt.nokia.com/}{http://bugreports.qt.nokia.com/}.
For information about mixing exceptions with Symbian leaves, see
\l{Exception Safety with Symbian}.
\section1 Required Capabilities
The Qt libraries are typically signed with \c{All -TCB} capabilites but
that does not mean your Qt application needs to be signed with the same
capabilities to function properly. The capabilities your application needs
to function properly depends on which parts of Qt you use.
In a Qt application Symbian capabilities are defined in the
\l {http://doc.qt.nokia.com/4.8/qmake-variable-reference.html#target-capability}
{TARGET.CAPABILITY} qmake variable in the project file.
Here is an overview for which capabilities may be needed when using different modules:
\table
\header \o Module
\o Required Symbian Capability
\row \o QtCore
\o \c PowerMgmt if QProcess::kill(...) or QProcess::terminate(...) is called.
\row \o QtCore
\o \c AllFiles when \l{http://wiki.forum.nokia.com/index.php/Capabilities_%28Symbian_Signed%29/AllFiles_Capability}{accessing specific areas.}
\row \o QtDeclarative
\o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified.
\row \o QtNetwork
\o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified.
\row \o QtNetwork
\o \c ReadUserData is required to include all the phone's SSL certificates in the system's default CA certificate list
(for example those added by the user or stored in the SIM card),
without this capability only the CA certs built into the phone are used.
\row \o QtMultimedia
\o \c UserEnvironment if QAudioInput is used.
\row \o QtWebKit
\o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified.
\endtable
\note Some modules rely on other modules. E.g. QtWebkit and QtDeclarative
depend on QtNetwork and therefore any application that
depends on these modules is also likely to need \c NetworkServices capability.
For more information see the documentation of the individual Qt classes. If
a class does not mention Symbian capabilities, it requires none.
\target Multimedia Support
\section1 Multimedia Support
Qt Mobility provides a high-level API for multimedia functionality with
\l{http://doc.qt.nokia.com/qtmobility/multimedia.html}{QtMultimediaKit}.
In addition, Qt provides the low-level \l {QtMultimedia}{QtMultimedia}
module that is internally used by the QtMultimediaKit. For more information
on developing multimedia applications for Symbian devices, see
\l {http://www.developer.nokia.com/info/sw.nokia.com/id/4abf12e7-72d8-45ef-b1a2-46184abe18ba/Guide_for_Qt_Multimedia_Developers.html}
{Guide for Qt Multimedia Developers}.
Moreover, there is a third multimedia-related module called Phonon. Qt
provides two backends for the Phonon module in Symbian: \i MMF and \i Helix.
Note that Phonon is a legacy module and the QtMultimediaKit module is
replacing Phonon in Qt 5. Although Phonon is supported in Symbian for
backwards compatibility and there is no plan to remove Phonon from Symbian
any new applications should use QtMultimediaKit in Symbian using Qt 4.7
bundle. The QtMultimediaKit feature set is comparable to that in Phonon.
The following applies to Phonon:
\list
\o MMF Phonon backend supports video and sound playback through Symbian's
Multimedia Framework, MMF. Phonon's video playback may show artifacts when
the video is moved or resized (for instance, during device orientation
changes from portrait to landscape and vice versa). This problem is present
on S60 5th Edition and earlier versions, as well as in Symbian Anna devices.
\o The audio and video formats that Phonon supports depends on what support
the platform provides for MMF. The emulator is known to have limited
codec support.
\o In addition, there exists a backend for the Helix framework. However, since
it is not shipped with Qt, its availability depends on the Symbian platform
in use. If the MFF plugin fails to load, the Helix plugin, if present on the
device, will be loaded instead.
\endlist
\section1 Hardware Accelerated Rendering
The default graphics system on Symbian Anna is OpenVG, which uses OpenVG
hardware to accelerate \l QPainter functions. There are a few exceptions,
where Qt will use software rendering fallback.
Devices like the N8 and C7 only have 32Mb of GPU memory and limited support
for EGL surface transparency. These devices can be identified by querying
the\c GL_RENDERER or \c VG_RENDERER string which evaluates to \c {VideoCore III}.
On these devices, Qt will use software rendering in cases listed below.
\list
\o Translucent windows
\o Dialogs
\o Popups
\endlist
\section1 OpenGL Support in Symbian
Qt 4.7 introduces the \l {QtOpenGL} module. QtOpenGL is
supported on devices which support OpenGL ES 2.0. Symbian platforms prior
to Symbian Anna (and Symbian^3) are not supported.
\l QGLWidget usage as a \l QGraphicsView viewport is not recommended on
Symbian. The OpenVG graphics system is not able to manage OpenGL graphics
resources. Also, a QGLWidget object is not able to release its GPU resources
when the application goes to the background. If OpenGL functionality is
needed, \l { http://doc.qt.nokia.com/4.7-snapshot/qapplication.html#setGraphicsSystem}
{OpenGL graphics system} usage is recommended. If an application
decides to use QGLWidget, then it is the application's responsibility to
destroy and release QGLWidget and related OpenGL resources when the
application goes to the background. Otherwise, the \l{Graphics Out Of Memory monitor}
may decide to kill the application as it consumes GPU resources while in the
background.
\note \l QGLBuffer, \l QGLFramebufferObject, \l QGLPixelBuffer, \l
QGLShader, and \l QGLShaderProgram are direct GPU resources and it is the
application's responsibility to manage them.
\section1 UI Performance in S60 3rd and 5th Edition Devices
Qt uses the QPainter class to perform low-level painting on widgets and
other paint devices. QPainter provides functions to draw complex shapes,
aligned text and pixmaps. It can also do vector path clipping, coordinate
transformations and Porter-Duff composition. If the underlying graphics
architecture does not support all of these operations then Qt uses the
raster graphics system for rendering.
In Symbian Anna (and Symbian^3) Qt uses hardware accelerated graphics as explained above.
This is enabled by \l
{http://library.developer.nokia.com/index.jsp?topic=/GUID-E35887BB-7E58-438C-AA27-97B2CDE7E069/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.html}
{ScreenPlay Graphics Architecture} in these devices.
Most of the Symbian S60 3rd and 5th Edition devices have a
graphics architecture that does not have native support for all functions
provided by QPainter. In these \l
{http://library.developer.nokia.com/index.jsp?topic=/GUID-E35887BB-7E58-438C-AA27-97B2CDE7E069/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.html}
{non-ScreenPlay} devices Qt uses the raster
graphics system by default that has a performance penalty compared
to native Symbian rendering.
In order to be able to perform all functions provided by QPainter, the
raster graphics system needs to have pixel level framebuffer access. To
make this possible in non-ScreenPlay devices Qt has to create an
additional offscreen buffer that is the target for all Qt rendering
operations. Qt renders the widget tree to the offscreen buffer and the
offscreen buffer is blitted to the framebuffer via Symbian Window Server.
The following table shows the rendering stacks of native Symbian and Qt in
\l {http://library.developer.nokia.com/index.jsp?topic=/GUID-E35887BB-7E58-438C-AA27-97B2CDE7E069/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.html}
{non-ScreenPlay devices}.
\table
\header \o Symbian
\o Qt
\row \o \image symbian-rendering-stack-non-screenplay.png
\o \image symbian-qt-rendering-stack-non-screenplay.png
\endtable
The following diagrams show a simplified sequence of drawing a pixmap in
a non-ScreenPlay device.
\table
\header \o Symbian
\row \o \image symbian-draw-pixmap-sequence.png
\endtable
\table
\header \o Qt
\row \o \image symbian-qt-draw-pixmap-sequence.png
\endtable
When compared to a native Symbian application, Qt does an additional blit
to the offscreen buffer before drawing to the framebuffer. That is the
performance penalty which needs to be paid to get all functionality
provided by QPainter in non-ScreenPlay architecture.
*/
|