Add Symbian platform notes.

2 files changed, 457 insertions, 1 deletions

diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc
new file mode 100644
index 0000000000..0022704e52
--- /dev/null
+++ b/doc/src/platforms/platform-notes.qdoc
@@ -0,0 +1,368 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 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.
+*/
+
diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc
index 38d4f16ab8..f69bddb68c 100644
--- a/doc/src/platforms/supported-platforms.qdoc
+++ b/doc/src/platforms/supported-platforms.qdoc
@@ -355,6 +355,93 @@
 
 */
 /*!
+    \page symbian-support.html
+    \title Support for Symbian
+    \brief Platform support for Symbian.
+    \ingroup platform-specific
+    \ingroup platform-details
+
+    \section1 Qt on Symbian
+
+    Qt provides support for the Symbian platform with integration
+    to the S60 framework. If you are developing apps for the Symbian,
+    Maemo or MeeGo platforms in most cases, you can use Qt under the
+    free LGPL licensing option. Qt is cross-platform, and that means
+    that you can use the code from one single code-base and rebuild
+    for all \l{Supported Platforms}{supported platforms}.
+
+     \section1 Getting Started on Symbian
+
+    \list
+        \o \l{Supported Platforms}{Supported platform}
+        - Details on the Qt support for Symbian.
+        \o \l{Qt for the Symbian platform Requirements}{Qt for the
+        Symbian platform Requirements} - Software required to run Qt
+        on Symbian.
+        \o \l{Installing Qt for the Symbian platform}{Installing Qt
+        for the Symbian platform} - Build Qt for Symbian development.
+        \o \l{Platform and Compiler Notes - Symbian}{Platform Notes - Symbian}
+        - Platform specific notes.
+        \o \l{Getting Started Guides}{Getting started}
+        \o \l{Qt Quick Components for Symbian 1.1}{Qt Quick Components for Symbian}
+        - provides a QML component set for the Symbian^3 platform
+    \endlist
+
+    \section1 Key Features for Symbian Development
+
+    On top of all the tools and the API and class libraries that Qt
+    offers, Qt provides you with added functionality for an optimized
+    Symbian development experience.
+
+    \section2 Native Look and Feel
+
+    Qt will detect which theme the phone is running and applies the
+    style at runtime to your Qt application. The look and feel of your
+    applications can also be easily customized in a fraction of the
+    time and lines of code required for traditional UI styling with
+    Qt Style Sheets.
+
+    The \l{Qt Quick Components for Symbian 1.1}{Qt Quick Components for Symbian 1.1}
+    provides a native QML component set.
+
+    \section2 Graphics Features
+
+    Qt for Symbian contains a powerful paint engine that provides
+    features such as anti, aliasing, gradients, curves and transparency.
+    It also has animation support with timelines and easing curves. It
+    is already targeting future device technology by supporting hardware
+    acceleration using OpenVG.
+
+    \section2 Device Configurations
+
+    Using Qt for Symbian all supported Symbian devices provides automatic
+    support for swiching between landscape and portrait mode, different
+    screen resolutions as well as touch screen and key pad input.
+
+    \section2 Cross-Platform Development using Qt Creator
+
+    \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is
+    a complete Cross-platform IDE included in the Qt SDK. The IDE allows
+    programmers to create, build, debug and run Qt applications accross all
+    supported platforms.
+
+    \section3 Licensing
+
+    Qt for Symbian is available under the Qt Commercial License, the LGPL
+    v. 2.1 "LGPL") and the GPL v. 3.0.  Symbian currently licenses their
+    software products under either the Symbian Foundation License or the
+    Eclipse Public License ("EPL"). While the LGPL and the EPL are not
+    compatible and may not be combined on a file-by-file basis, they may
+    be used in a common environment provided that the interaction between
+    Qt and Symbian is limited to:  dynamic linking, inter-process
+    communication and data exchange. Therefore, most Symbian developers
+    can use Qt for Symbian under the LGPL.
+
+    Additional \l{Cross-Platform and Platform-Specific Development}
+    information.
+
+*/
+/*!
     \page supported-platforms.html
     \title Supported Platforms
     \brief The platforms supported by Nokia for Qt.
@@ -373,12 +460,13 @@
     \o {2,1} Qt Cross Platform Support
     \header
     \o {1,1} Desktop
-    \o {1,1} Embedded
+    \o {1,1} Embedded/Mobile
     \row
     \o \l{Support for Windows}{Windows}
     \o \l{Support for Embedded Linux}{Embedded Linux}
     \row
     \o \l{Support for Linux/X11}{Linux/X11}
+    \o \l{Support for Symbian}{Symbian}
     \row
     \o \l{Support for Mac OS X}{Mac OS X}
     \endtable