Doc updates to installation, platform notes and symbian introduction.

3 files changed, 133 insertions, 137 deletions

diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc
index bec9ee42c7..c166794772 100644
--- a/doc/src/getting-started/installation.qdoc
+++ b/doc/src/getting-started/installation.qdoc
@@ -504,75 +504,27 @@ in the \l{Qt for Windows CE Requirements} document.
 
 \tableofcontents
 
-Qt for the Symbian platform has some requirements that are given in more detail
-in the \l{Qt for the Symbian platform Requirements} document.
-
-
-\section1 Step 1: Install Qt
-
-        Download the \c {Qt libraries 4.x for Windows} package (for \c minGW or \c {VS 2008}) 
-        from the \l {http://qt.nokia.com/downloads#qt-lib}{downloads} page.
-        
-        Run the downloaded package and follow the instructions.
-
-        \note Qt must be installed on the same drive as the Symbian SDK you are
-        using, and the install path must not contain any spaces.
-
-\section1 Step 2: Install Qt into a device
-
-        To run Qt applications on a device, \c{qt_installer.sis} found
-        in the Qt installation directory must be first installed into the device.
-        \c{Qt_installer.sis} contains Qt libraries and Open C libraries all in one
-        convenient package.
-        Begin installation by connecting your device via USB cable to a computer that
-        has the \l{http://www.nokia.com/pcsuite}{Nokia PC Suite} installed.
-        On the device, select "PC Suite mode". In Windows Explorer right click
-        on the \c{qt_installer.sis} file, select "Install with Nokia Application
-        Installer" and follow the instructions.
-
-\section1 Running Qt demos
-
-        We've included a subset of the Qt demos in this package for you
-        to try out. An excellent starting point is the "fluidlauncher"
-        demo.
-
-        To run the demo on a real device, install \c{fluidlauncher.sis}
-        found in the Qt installation directory to a device that already has Qt installed.
-        After installation, you can find fluidlauncher in the applications folder of the device.
-
-        To run the demos and examples on the emulator, you need to build them first.
-        Open the "Qt for the Symbian platform Command Prompt" from the Start menu and type:
-
-        \snippet doc/src/snippets/code/doc_src_installation.qdoc 25
-
-        To run the demos on the emulator simply navigate to the directory of the demo
-        you want to see and run:
-
-        \snippet doc/src/snippets/code/doc_src_installation.qdoc 27
-
-        For more information about building and running Qt programs on the
-Symbian platform,
-        see \l{The Symbian platform - Introduction to Qt}.
-
-\bold{We hope you will enjoy using Qt.}
-
+    Qt for Symbian binary packages (SIS files) are available from the \l 
+    {http://qt.nokia.com/downloads}{Qt SDK}.
 
 */
 /*! \page install-Symbian.html
-\title Installing Qt for the Symbian platform
+\title Installing Qt for the Symbian Platform
 \ingroup installation
 \ingroup qtsymbian
 \brief How to install Qt for the Symbian platform.
 \previouspage Installation
 \tableofcontents
 
+    \l {http://qt.nokia.com/downloads}{Qt SDK} provides all the necessary tools 
+    and libraries for developing Qt applications. However, if you want to build 
+    Qt itself for Symbian, follow the instructions below.
+
 Qt for the Symbian platform has some requirements that are given in more detail
 in the \l{Qt for the Symbian platform Requirements} document.
 
 This document describes how to install and configure Qt for
-the Symbian platform from scratch. If you are using pre-built binaries, follow 
-the instructions given in the \l{Installing Qt for the Symbian platform from a 
-Binary Package} document.
+the Symbian platform from scratch.
 
 \section1 Step 1: Set Up the Development Environment
 
diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc
index d33a7a9500..fbb66b12aa 100644
--- a/doc/src/platforms/platform-notes.qdoc
+++ b/doc/src/platforms/platform-notes.qdoc
@@ -622,7 +622,10 @@
     \ingroup platform-specific
     \brief Information about the state of support for the Symbian platform.
 
-    This page documents the current notes for the Symbian port.
+    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
 
@@ -635,10 +638,10 @@
 
     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 
-    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.
+    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 
@@ -648,73 +651,93 @@
     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.
 
-    \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian#Supported_Devices}{Nokia Smart Installer for Symbian}
-    documentation lists supported 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.
+    \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.
+    \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 Supported Functionality
-
-    The following technologies and classes are not currently supported:
-
-    \table
-    \header \o Technology
-            \o Note
-    \row    \o QtConcurrent
-            \o Planned for future release.
-    \row    \o QtDBus
-            \o No current plans to support this feature.
-    \row    \o Printing support
-            \o No current plans to support this feature.
-    \row    \o Qt3Support
-            \o No current plans to support this feature.
-    \endtable
+    \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 Technology
+    \header \o Module
             \o Note
     \row    \o QtSql
             \o The only supported driver is SQLite.
     \row    \o QtMultimedia
-            \o For support details see \l {Multimedia and Phonon Support} section.
+            \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
-    
-    It is not recommended to use the following Qt widgets:
-    \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 QMdiSubWindow
-    \o QDockWidget
-    \o QPrintPreviewWidget
-    \endlist
 
     \section1 Compiler Notes
-
-    \section2 GCCE (Symbian)
-
-    GCCE cannot be used to compile Qt libaries for the Symbian platform, but GCCE is supported
-    when compiling Qt applications for the Symbian platform.
+    
+    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
 
@@ -730,11 +753,14 @@
 
     \section1 Required Capabilities
 
-    The Qt libraries are typically signed with \c{All -TCB} capabilites, but
+    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, here is an
-    overview:
+    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
@@ -751,9 +777,9 @@
             \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
+    \row    \o QtMultimedia
             \o \c UserEnvironment if QAudioInput is used.
-    \row    \o QtWebkit
+    \row    \o QtWebKit
             \o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified.
     \endtable
 
@@ -764,30 +790,41 @@
     For more information see the documentation of the individual Qt classes. If
     a class does not mention Symbian capabilities, it requires none.
 
-    \target Multimedia and Phonon Support
-    \section1 Multimedia and Phonon Support
+    \target Multimedia Support
+    \section1 Multimedia Support
 
-    Qt provides a high-level API for multimedia functionality with
-    (\l{http://doc.qt.nokia.com/qtmobility/multimedia.html}).
+    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}.
 
-    Qt also provides a backend for Qt's Phonon module, which supports video and
-    sound playback through Symbian's Multimedia Framework, MMF. Note that Phonon
-    support is not being extended, and that Qt's multimedia module will
-    take over for Phonon at a later stage.
+    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. 
 
-    In this release the support is experimental. Video playback may show
-    artifacts when the video is moved or resized (for instance during
-    orientation flips). This problem is present on S60 5th Edition and earlier
-    versions, and on Symbian^3 systems.
+    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 audio and video formats that Phonon supports depends on what support
+    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.
-
-    In addition, there exists a backend for the Helix framework. However, since
+    \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
 
@@ -806,17 +843,18 @@
         \o Popups
         \endlist
 
-    \section1 QtOpenGL Support in Symbian
+    \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^3 are not supported.
+     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, OpenGL graphics system usage is recommended. If an application
+    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}
@@ -827,7 +865,7 @@
     QGLShader, and \l QGLShaderProgram are direct GPU resources and it is the
     application's responsibility to manage them.
 
-    \section1 UI Performance in devices prior to Symbian^3
+    \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,
@@ -835,11 +873,18 @@
     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.
-
-    Most of the Symbian devices prior to Symbian^3 use a non-ScreenPlay
-    graphics architecture which does not have native support for all functions
-    provided by QPainter. In non-ScreenPlay devices Qt uses the raster
-    graphics system by default which has a performance penalty when compared
+    
+    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
@@ -850,7 +895,8 @@
     offscreen buffer is blitted to the framebuffer via Symbian Window Server.
 
     The following table shows the rendering stacks of native Symbian and Qt in
-    non-ScreenPlay devices.
+    \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
diff --git a/doc/src/platforms/symbian-introduction.qdoc b/doc/src/platforms/symbian-introduction.qdoc
index 2a5d5b16bb..82d39f32a4 100644
--- a/doc/src/platforms/symbian-introduction.qdoc
+++ b/doc/src/platforms/symbian-introduction.qdoc
@@ -42,7 +42,6 @@
     \o
      \list
         \o \l {Qt for the Symbian platform Requirements}
-        \o \l {Installing Qt for the Symbian platform from a Binary Package}
         \o \l {Installing Qt for the Symbian platform}
         \o \l {The Symbian platform - Introduction to Qt}{Introduction to using Qt}
     \endlist
@@ -55,7 +54,7 @@
     \endlist
     \o
     \list
-        \o \l {Deploying an Application on the Symbian platform}{Deploying Applications}
+        \o \l {Deploying an Application on the Symbian Platform}{Deploying Applications}
     \endlist
     \endtable
 */
@@ -74,6 +73,8 @@
     Platform security capabilities are added via the
     \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
     qmake variable.
+
+    \sa {platform-notes-symbian.html#required-capabilities}{Required Capabilities}
 */
 
 /*!
@@ -93,9 +94,6 @@
 
     \section1 Installing Qt and Running Demos
 
-    Follow the instructions found in \l{Installing Qt for the Symbian platform from a Binary Package}
-    to learn how to install Qt using a binary package and how to build and run Qt demos.
-
     Follow the instructions found in \l{Installing Qt for the Symbian platform} to learn how to install Qt using
     using source package and how to build and run the Qt demos.