Doc: move new files into correct subdirectory.

2 files changed, 392 insertions, 0 deletions

diff --git a/doc/src/platforms/s60-introduction.qdoc b/doc/src/platforms/s60-introduction.qdoc
new file mode 100644
index 0000000..d0a1976
--- /dev/null
+++ b/doc/src/platforms/s60-introduction.qdoc
@@ -0,0 +1,151 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 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:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page s60-with-qt-introduction.html
+
+    \title S60 - Introduction to using Qt
+    \brief An introduction to Qt for S60 developers.
+    \ingroup howto
+    \ingroup qts60
+
+    \tableofcontents
+
+    \section1 Required tools
+    
+    See \l{Qt for S60 Requirements} to see what tools are required to use Qt for S60.
+
+    \section1 Installing Qt and running demos
+    
+    Follow the instructions found in \l{Installing Qt on S60 using binary package} to learn how
+    to install Qt using binary package and how to build and run Qt demos.
+
+    Follow the instructions found in \l{Installing Qt on S60} to learn how to install Qt using
+    using source package and how to build and run the Qt demos.
+
+    \section1 Building your own applications
+
+    If you are new to Qt development, have a look at \l{How to Learn Qt}. 
+    In general, the difference between developing a
+    Qt application on S60 compared to any of the other platforms supported
+    by Qt is not that big.
+
+    Once you have crated a \c .pro file for your project, generate the
+    Carbide specific \c Bld.inf and \c .mmp files this way:
+
+    \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 0
+
+    For more information on how to use qmake have a look at the \l
+    {qmake Tutorial}.
+
+    Now you can build the Qt on S60 application with standard build
+    tools. By default, running \c make will produce binaries for the
+    emulator. However, S60 comes with several alternative build targets,
+    as shown in the table below:
+
+    \table
+    \row \o \c debug-winscw  \o Build debug binaries for the emulator (default).
+                                It is currently not possible to build release
+                                binaries for the emulator.
+    \row \o \c debug-gcce    \o Build debug binaries for hardware using GCCE.
+    \row \o \c release-gcce  \o Build release binaries for hardware using GCCE.
+    \row \o \c debug-armv5   \o Build debug binaries for hardware using RVCT.
+    \row \o \c release-armv5 \o Build release binaries for hardware using RVCT.
+    \row \o \c run           \o Run the emulator binaries from the build directory.
+    \row \o \c sis           \o Create signed \c .sis file for project.
+    \endtable
+
+    The following lines perform a debug build for the emulator
+    and deploy all the needed files:
+
+    \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 1
+
+    To work on your project in Carbide, simply import the \c .pro file
+    by right clicking on the project explorer and executing "Import...".
+
+    \section1 Installing your own applications
+
+    To install your own applications on hardware, you need signed \c .sis file.
+    The signed \c .sis file can be created with \c make \c sis target. \c sis target
+    is only supported for executables or projects with \c DEPLOYMENT statements.
+    By default the \c sis target will create signed \c .sis file for last build
+    target. For example, the following sequence will generate the needed makefiles, 
+    build the project for \c debug-winscw and \c release-armv5, and create 
+    self-signed \c .sis file for \c release-armv5 target:
+    
+    \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 2
+
+    If you want to use different certificate information or override the default
+    target for \c .sis file creation you can use the environment variables as 
+    shown in the table below:
+    
+    \table
+    \row \o \c QT_SIS_OPTIONS      \o Options accepted by \c .sis creation. 
+                                       -i, install the package right away using PC suite.
+                                       -c=<file>, read certificate information from a file.
+                                       Execute \c{perl createpackage.pl} for more information
+                                       about options.
+                                       By default no otions are given.
+    \row \o \c QT_SIS_TARGET       \o Target for which \c .sis file is created.
+                                       Accepted values are build targets listed in 
+                                       previous table. By default last build target.
+    \row \o \c QT_SIS_CERTIFICATE  \o The certificate file used for signing.
+                                       By default self-signed certificate. 
+    \row \o \c QT_SIS_KEY          \o The certificate's private key file.
+                                       By default key is associated to self-signed certificate. 
+    \row \o \c QT_SIS_PASSPHRASE   \o The certificate's private key file's passphrase.
+                                       By default empty. 
+    \endtable    
+    
+    For example:
+    
+    \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 4        
+
+    The environment variables for \c make can also be given as parameters:
+    
+    \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 3        
+    
+    If you want to install the program immediately, make sure that the device
+    is connected to the computer in "PC Suite" mode, and run \c sis target
+    with the \c QT_SIS_OPTIONS=-i, like this:
+
+    \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 5
+*/
diff --git a/doc/src/platforms/symbian-exceptionsafety.qdoc b/doc/src/platforms/symbian-exceptionsafety.qdoc
new file mode 100644
index 0000000..88f4d03
--- /dev/null
+++ b/doc/src/platforms/symbian-exceptionsafety.qdoc
@@ -0,0 +1,241 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 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:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page symbianexceptionsafety.html
+    \title Exception Safety with Symbian
+    \ingroup qts60
+    \brief A guide to integrating exception safety in Qt with Symbian.
+
+    The following sections describe how Qt code can interoperate with Symbian's
+    exception safety system.
+
+    \tableofcontents
+
+    \section1 What the problem is
+    
+    Qt and Symbian have different exception systems. Qt works with standard C++ 
+    exceptions, whereas Symbian has its TRAP/Leave/CleanupStack system. So, what would 
+    happen if you mix the two systems? It could go wrong in a number of ways.
+
+    Clean-up ordering would be different between the two. When Symbian code 
+    leaves, the clean-up stack is cleaned up before anything else happens. After 
+    that, the objects on the call stack would be cleaned up as with a normal 
+    exception. So if there are any dependencies between stack-based and  
+    objects owned by the clean-up stack, there could be problems due to this
+    ordering.
+
+    Symbian's \c XLeaveException, which is used when Symbian implements leaves as 
+    exceptions, is not derived from \c std::exception, so would not be caught in 
+    Qt catch statements designed to catch \c std::exception. 
+
+    Qt's and standard C++'s \c std::exception derived exceptions result in program 
+    termination if they fall back to a Symbian TRAP. 
+
+	These problems can be solved with barrier macros and helper functions that 
+	will translate between the two exception systems. Use them, in Qt code, 
+	whenever calling into or being called from Symbian code.
+
+    \section1 Qt calls to Symbian
+
+    When calling Symbian leaving functions from Qt code, we want to translate 
+    Symbian leaves to standard C++ exceptions. The following help is provided:
+
+    \list
+        \o \l qt_symbian_throwIfError() takes a Symbian
+        error code and throws an appropriate exception to represent it. 
+        This will do nothing if the error code is not in fact an error. The 
+        function is equivalent to Symbian's \c User::LeaveIfError.
+        \o \l q_check_ptr() takes a pointer and throws a std::bad_alloc
+        exception if it is 0, otherwise the pointer is returned. This can be
+        used to check the success of a non-throwing allocation, eg from
+        \c malloc(). The function is equivalent to Symbian's \c
+        User::LeaveIfNull.
+        \o \l QT_TRAP_THROWING() takes a Symbian leaving
+        code fragment f and runs it under a trap harness converting any resulting 
+        error into an exception.
+        \o \c TRAP and \c TRAPD from the Symbian libraries can be used to convert 
+        leaves to error codes. 
+    \endlist
+
+    \code
+    HBufC* buf=0;
+    // this will throw a std::bad_alloc because we've asked for too much memory
+    QT_TRAP_THROWING(buf = HBufC::NewL(100000000));
+
+    _LIT(KStr,"abc");
+    TInt pos = KStr().Locate('c');
+    // pos is a good value, >= 0, so no exception is thrown
+    qt_symbian_throwIfError(pos);
+    
+    pos = KStr().Locate('d');
+    // pos == KErrNotFound, so this throws an exception
+    qt_symbian_throwIfError(pos);
+    
+    // we are asking for a lot of memory, HBufC::New may return NULL, so check it
+    HBufC *buffer = q_check_ptr(HBufC::New(1000000));
+    \endcode
+    
+    \section2 Be careful with new and CBase
+    
+    When writing Qt code, \c new will normally throw a \c std::bad_alloc if the
+    allocation fails. However this may not happen if the object being created
+    has its own \c {operator new}. For example, CBase and derived classes have
+    their own \c {operator new} which returns 0 and the \c {new(ELeave)}
+    overload for a leaving \c {operator new}, neither of which does what we want.
+    When using 2-phase construction of CBase derived objects, use \c new and
+    \l q_check_ptr().
+    
+    \oldcode
+    CFbsBitmap* fbsBitmap = new(ELeave) CFbsBitmap;
+    \newcode
+    CFbsBitmap* fbsBitmap = q_check_ptr(new CFbsBitmap);
+    \endcode
+    
+    \section1 Qt called from Symbian
+
+    When Qt code is called from Symbian, we want to translate standard C++ 
+    exceptions to Symbian leaves or error codes. The following help is 
+    provided:
+
+    \list
+        \o \l qt_symbian_exception2Error() -
+        this takes a standard exception and gives an appropriate Symbian 
+        error code. If no mapping is known for the exception type, 
+        \c KErrGeneral is returned.
+        \o \l qt_symbian_exception2LeaveL() -
+        this takes a standard exception and generates an appropriate Symbian 
+        leave.
+        \o \l QT_TRYCATCH_ERROR() - this macro
+        takes the standard C++ code fragment \c f, catches any std::exceptions 
+        thrown from it, and sets err to the corresponding Symbian error code. 
+        err is set to \c KErrNone otherwise.
+        \o \l QT_TRYCATCH_LEAVING() - this macro takes the
+        standard C++ code fragment \c f, catches any std::exceptions thrown from 
+        it, and throws a corresponding Symbian leave. 
+    \endlist
+    
+    \code
+    TInt DoTickL() // called from an active object RunL, ie Symbian leaves expected
+        {
+        // without the translation to Symbian Leave, we get a USER:0 panic
+        QT_TRYCATCH_LEAVING({
+            int* x = new int[100000000];            // compiled as Qt code, will throw std::bad_alloc
+            delete [] x;
+        });
+        return 0;
+        }
+    \endcode
+
+    \section1 Common sense things
+
+    Try to minimise the interleaving of Symbian and Qt code, every switch 
+    requires a barrier. Grouping the code styles in different blocks will 
+    minimise the problems. For instance, examine the following code.
+
+    \code
+    1.    TRAPD(err, m_playUtility = CMdaAudioPlayerUtility::NewL(*this);
+    2.               QString filepath = QFileInfo( m_sound->fileName() ).absoluteFilePath();
+    3.               filepath = QDir::toNativeSeparators(filepath);
+    4.               m_playUtility->OpenFileL(qt_QString2TPtrC(filepath)));
+    \endcode
+
+    Line 1 starts a Symbian leave handling block, which is good because it 
+    also uses a Symbian leave generating function.
+
+    Line 2 creates a \l QString, uses \l QFileInfo and various member functions. 
+    These could all throw exceptions, which is not good inside a \c TRAP block.
+
+    Line 3 is unclear as to whether it might throw an exception, but since 
+    it's dealing with strings it probably does, again bad.
+
+    Line 4 is tricky, it calls a leaving function which is ok within a \c TRAP, 
+    but it also uses a helper function to convert string types. In this case
+    the helper function may cause an unwelcome exception.
+
+    We could rewrite this with nested exception translations, but it's much 
+    easier to refactor it. 
+
+    \code
+    QString filepath = QFileInfo( m_sound->fileName() ).absoluteFilePath();
+    filepath = QDir::toNativeSeparators(filepath);
+    TPtrC filepathPtr(qt_QString2TPtrC(filepath));
+    TRAPD(err, m_playUtility = CMdaAudioPlayerUtility::NewL(*this);
+               m_playUtility->OpenFileL(filepathPtr));
+    \endcode
+
+    Now the exception generating functions are separated from the leaving 
+    functions.
+
+    \section1 Advanced technique
+    When using Symbian APIs in Qt code, you may find that Symbian leaving 
+    code and Qt exception throwing code are just too mixed up to have
+    them interoperate through barriers. In some circumstances you can allow
+    code to both leave and throw exceptions. But you must be aware of the 
+    following issues:
+    
+    \list
+        \o Depending on whether a leave or exception is thrown, or a normal
+           exit happens, the cleanup order will vary. If the code leaves,
+           cleanup stack cleanup will happen first. On an exception however,
+           cleanup stack cleanup will happen last.
+        \o There must not be any destructor dependencies between different
+           code styles. That is, you must not have symbian objects using Qt
+           objects in their destructors, and vice versa. This is because the
+           cleanup order varies, and may result in objects being used after
+           they are deleted.
+        \o The cleanup stack must not refer to any stack based object. For 
+           instance, in Symbian you may use \c CleanupClosePushL() to push 
+           stack based R-classes onto the cleanup stack. However if the 
+           stack has unwound due to an exception before the cleanup stack 
+           cleanup happens, stack based objects will now be invalid.
+           Instead of using the cleanup stack, consider Symbian's new
+           \c LManagedHandle<> (or a custom cleanup object) to tie R-class 
+           cleanup to the stack.
+        \o Mixed throwing code must be called within both a TRAP and a 
+           try/catch harness. Standard exceptions must not propagate to
+           the TRAP and cleanup stack cleanup will only happen if a leave
+           is thrown, so the correct pattern is either \c {TRAPD(err, 
+           QT_TRYCATCH_LEAVING( f ));} or \c {QT_TRAP_THROWING(
+           QT_TRYCATCH_LEAVING( f ));}, depending if you want an error
+           code or exception as a result.
+    \endlist
+*/