diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/development/qmake-manual.qdoc | 458 | ||||
| -rw-r--r-- | doc/src/examples/htmlinfo.qdoc | 89 | ||||
| -rw-r--r-- | doc/src/exceptionsafety.qdoc | 156 | ||||
| -rw-r--r-- | doc/src/getting-started/installation.qdoc | 177 | ||||
| -rw-r--r-- | doc/src/howtos/appicon.qdoc | 15 | ||||
| -rw-r--r-- | doc/src/platforms/emb-install.qdoc | 4 | ||||
| -rw-r--r-- | doc/src/platforms/platform-notes.qdoc | 13 | ||||
| -rw-r--r-- | doc/src/s60-introduction.qdoc | 117 | ||||
| -rw-r--r-- | doc/src/snippets/code/doc_src_appicon.qdoc | 4 | ||||
| -rw-r--r-- | doc/src/snippets/code/doc_src_installation.qdoc | 38 | ||||
| -rw-r--r-- | doc/src/snippets/code/doc_src_qmake-manual.qdoc | 119 | ||||
| -rw-r--r-- | doc/src/snippets/code/doc_src_s60-introduction.qdoc | 16 | ||||
| -rw-r--r-- | doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp | 103 | ||||
| -rw-r--r-- | doc/src/symbian-exceptionsafety.qdoc | 241 |
14 files changed, 1519 insertions, 31 deletions
diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index 181ba6a77..5fdc4e86d 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -918,6 +918,89 @@ This is discussed in more detail in the \l{Deploying an Application on Windows#Visual Studio 2005 Onwards} {deployment guide for Windows}. + + + \section1 S60 + + Features specific to this platform include handling of static data, + capabilities, stack and heap size, compiler specific options, and unique + identifiers for the application or library. + + \section2 Handling of static data + + If the application uses any static data, the build system needs to be + informed about it. This is because Symbian tries to save memory if no + static data is in use. + + To specify that static data support is desired, add this to the project file: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 129 + + The default value is zero. + + \section2 Stack and heap size + + Symbian uses predefined sizes for stacks and heaps. If an + application exceeds either limit, it may crash or fail to complete its + task. Crashes that seem to have no reason can often be traced back to + insufficient stack and/or heap sizes. + + The stack size has a maximum value, whereas the heap size has a + minimum and a maximum value, all specified in bytes. The minimum value + prevents the application from starting if that amount of memory is not available. The + minimum and maximum values are separated by a space. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 130 + + The default values depend on the version of the S60 SDK you're using. + + \section2 Compiler specific options + + General compiler options can as usual be set using \c QMAKE_CFLAGS and \c QMAKE_CXXFLAGS. + In order to set specific compiler options, \c QMAKE_CFLAGS.<compiler> and + \c QMAKE_CXXFLAGS.<compiler> can be used. \c <compiler> can be either \c CW for the WINSCW + architecture (emulator), or \c ARMCC for the ARMv5 architecture (hardware). + + Here is an example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 131 + + \section2 Unique identifiers + + Symbian applications may have unique identifiers attached to them. + Here is how to define them in a project file: + + There are four types of IDs supported: \c UID2, \c UID3, \c SID, and \c VID. They + are specified like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 132 + + If \c UID2 is not specified, it defaults to the same value as \c UID3. + If \c UID3 is not specified, qmake will automatically generate a \c UID3 + suitable for development and debugging. This value should be manually + specified for applications that are to be released. In order to optain + an official UID, please contact Nokia. Both \c SID and \c VID default to empty values. + + For more information about unique identifiers and their meaning for + Symbian applications, please refer to the + \l{http://www.symbian.com/developer/techlib/v9.2docs/doc_source/ToolsAndUtilities/BuildTools/UsingUids.guide.html}{respective S60 SDK documentation}. + + \section2 Capabilities + + Capabilities define extra priviledges for the application, such as the + ability to list all files on the file system. Capabilities are defined + in the project file like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 133 + + It is also possible to specify which capabilities \e not to have, + by first specifying \c ALL and then list the unwanted capabilities + with a minus in front of them, like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 134 + + For more information about capabilities, please refer to the + \l{http://www.symbian.com/developer/techlib/v9.2docs/doc_source/guide/platsecsdk/index.html}{respective S60 SDK documentation}. */ /*! @@ -1008,6 +1091,32 @@ \tableofcontents{3} + \target BLD_INF_RULES + \section1 BLD_INF_RULES + + \e {This is only used on Symbian.} + + Generic \c bld.inf file content can be specified with \c BLD_INF_RULES variables. + The section of \c bld.inf file where each rule goes is appended to + \c BLD_INF_RULES with a dot. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 146 + + This will add the specified statements to the \c prj_exports section of the + generated \c bld.inf file. + + It is also possible to add multiple rows in a single block. Each double + quoted string will be placed on a new row in the generated \c bld.inf file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 143 + + Any rules you define will be added after automatically generated + rules in each section. + \target CONFIG \section1 CONFIG @@ -1178,6 +1287,20 @@ The build process for bundles is also influenced by the contents of the \l{#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA} variable. + These options only have an effect on Symbian: + + \table 95% + \header \o Option \o Description + \row \o stdbinary \o Builds an Open C binary (i.e. STDDLL, STDEXE, or STDLIB, + depending on the target binary type.) + \row \o no_icon \o Doesn't generate resources needed for displaying an icon + for executable in application menu (app only). + \row \o symbian_test \o Places mmp files and extension makefiles under + test sections in generated bld.inf instead of their regular sections. + Note that this only affects automatically generated bld.inf content; + the content added via \c BLD_INF_RULES variable is not affected. + \endtable + These options have an effect on Linux/Unix platforms: \table 95% @@ -1221,7 +1344,7 @@ \target DEPLOYMENT \section1 DEPLOYMENT - \e {This is only used on Windows CE.} + \e {This is only used on Windows CE and Symbian.} Specifies which additional files will be deployed. Deployment means the transfer of files from the development system to the target device or @@ -1239,7 +1362,8 @@ The default deployment target path for Windows CE is \c{%CSIDL_PROGRAM_FILES%\target}, which usually gets expanded to - \c{\Program Files\target}. + \c{\Program Files\target}. For Symbian, the default target is the application + private directory on the drive it is installed to. It is also possible to specify multiple \c sources to be deployed on target \c paths. In addition, different variables can be used for @@ -1249,24 +1373,85 @@ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 29 - \note All linked Qt libraries will be deployed to the path specified - by \c{myFiles.path}. + \note In Windows CE all linked Qt libraries will be deployed to the path + specified by \c{myFiles.path}. In Symbian all libraries and executables + will always be deployed to the \\sys\\bin of the installation drive. + + Since the Symbian build system automatically moves binaries to certain + directories under the epoc32 directory, custom plugins, executables or + dynamically loadable libraries need special handling. When deploying + extra executables or dynamically loadable libraries, the target path + must specify \\sys\\bin. For plugins, the target path must specify the + location where the plugin stub will be deployed to (see the + \l{How to Create Qt Plugins} document for more information about plugins). + If the binary cannot be found from the indicated source path, + the directory Symbian build process moves the executables to is + searched, e.g. \\epoc32\\release\\armv5\\urel. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 128 + In Symbian, generic PKG file content can also be specified with this + variable. You can use either \c pkg_prerules or \c pkg_postrules to + pass raw data to PKG file. The strings in \c pkg_prerules are added before + package-body and \c pkg_postrules after. The strings defined in + \c pkg_postrules or \c pkg_prerules are not parsed by qmake, so they + should be in a format understood by Symbian package generation tools. + Please consult Symbian documentation for correct syntax. + + For example, to deploy DLL and add a new dependency: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 140 + + Please note that \c pkg_prerules can also replace default statements in + pkg file. If no pkg_prerules is defined, qmake makes sure that PKG file + syntax is correct and it contains all mandatory statements such as: + + \list + \o languages, for example \BR + &EN,FR + \o package-header, for example \BR + #{"MyApp-EN", "MyApp-FR"}, (0x1000001F), 1, 2, 3, TYPE=SA + \o localized and unique vendor, for example \BR + %{"Vendor-EN", ..., "Vendor-FR"} + :"Unique vendor name" + \endlist + + If you decide to override any of these statements, you need to pay + attention that also other statements stay valid. For example if you + override languages statement, you must override also package-header + statement and all other statements which are language specific. + + In Symbian, the \c default_deployment item specifies + default platform dependencies. It can be overwritten if a more + restrictive set is needed - e.g. if a specific + device is required to run the application. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 141 + \target DEPLOYMENT_PLUGIN \section1 DEPLOYMENT_PLUGIN - \e {This is only used on Windows CE.} + \e {This is only used on Windows CE and Symbian.} This variable specifies the Qt plugins that will be deployed. All plugins available in Qt can be explicitly deployed to the device. See \l{Static Plugins}{Static Plugins} for a complete list. - \note No plugins will be deployed automatically. If the application - depends on plugins, these plugins have to be specified manually. + \note In Windows CE, No plugins will be deployed automatically. + If the application depends on plugins, these plugins have to be specified + manually. + + \note In Symbian, all plugins supported by this variable will be deployed + by default with Qt libraries, so generally using this variable is not + needed. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 128 + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 142 This will upload the jpeg imageformat plugin to the plugins directory on the Windows CE device. @@ -1366,7 +1551,14 @@ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 34 See also \l{#SOURCES}{SOURCES}. - + + \target ICON + \section1 ICON + + This variable is used only in MAC and S60 to set the application icon. + Please see \l{Setting the Application Icon}{the application icon documentation} + for more information. + \target INCLUDEPATH \section1 INCLUDEPATH @@ -1430,9 +1622,9 @@ This variable contains a list of libraries to be linked into the project. You can use the Unix \c -l (library) and -L (library path) flags and qmake - will do the correct thing with these libraries on Windows (namely this - means passing the full path of the library to the linker). The only - limitation to this is the library must exist, for qmake to find which + will do the correct thing with these libraries on Windows and Symbian + (namely this means passing the full path of the library to the linker). The + only limitation to this is the library must exist, for qmake to find which directory a \c -l lib lives in. For example: @@ -1454,6 +1646,14 @@ explicitly specify the library to be used by including the \c{.lib} file name suffix. + \bold{Note:} On S60, the build system makes a distinction between shared and + static libraries. In most cases, qmake will figure out which library you + are refering to, but in some cases you may have to specify it explicitly to + get the expected behavior. This typically happens if you are building a + library and using it in the same project. To specify that the library is + either shared or static, add a ".dll" or ".lib" suffix, respectively, to the + library name. + By default, the list of libraries stored in \c LIBS is reduced to a list of unique names before it is used. To change this behavior, add the \c no_lflags_merge option to the \c CONFIG variable: @@ -1489,6 +1689,37 @@ when generating a Makefile. The value of this variable is typically handled internally by \c qmake and rarely needs to be modified. + \target MMP_RULES + \section1 MMP_RULES + + \e {This is only used on Symbian.} + + Generic MMP file content can be specified with this variable. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 137 + + This will add the specified statement to the end of the generated MMP file. + + It is also possible to add multiple rows in a single block. Each double + quoted string will be placed on a new row in the generated MMP file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 138 + + If you need to include a hash (\c{#}) character inside the + \c MMP_RULES statement, it can be done with the variable + \c LITERAL_HASH as follows: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 139 + + \note You should not use this variable to add MMP statements that are + explicitly supported by their own variables, such as + \c TARGET.EPOCSTACKSIZE. + Doing so could result in duplicate statements in the MMP file. + \target MOC_DIR \section1 MOC_DIR @@ -1781,6 +2012,14 @@ the \c QMAKE_CXXFLAGS_DEBUG and \c QMAKE_CXXFLAGS_RELEASE variables, respectively. + \bold{Note:} On S60, this variable can be used to pass architecture specific + options to each compiler in the Symbian build system. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 131 + + For more information, see + \l{qmake Platform Notes#Compiler specific options}{qmake Platform Notes}. + \target QMAKE_CXXFLAGS_DEBUG \section1 QMAKE_CXXFLAGS_DEBUG @@ -2568,6 +2807,49 @@ This variable contains the name of the resource file for the application. The value of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target RSS_RULES + \section1 RSS_RULES + + \e {This is only used on Symbian.} + + Generic RSS file content can be specified with this variable. The syntax is + similar to \c MMP_RULES and \c BLD_INF_RULES. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 144 + + This will add the specified statement to the end of the generated + registration resource file. As an impact of this statement, the application + will not be visible in application shell. + + It is also possible to add multiple rows in a single block. Each double + quoted string will be placed on a new row in the registration resource file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 145 + + This example will install the application to MyFolder in S60 application + shell. In addition it will make the application to be launched in background. + + For detailed list of possible RSS statements, please refer to Symbian OS help. + + \note You should not use \c RSS_RULES variable to set the following RSS statements: + + app_file + localisable_resource_file + localisable_resource_id + + These statements are internally handled by qmake. + + \target S60_VERSION + \section1 S60_VERSION + + \e {This is only used on Symbian.} + + Contains the version number of the underlying S60 SDK; e.g. "5.0". \target SIGNATURE_FILE \section1 SIGNATURE_FILE @@ -2632,6 +2914,78 @@ The project file above would produce an executable named \c myapp on unix and 'myapp.exe' on windows. + \target TARGET.CAPABILITY + \section1 TARGET.CAPABILITY + + \e {This is only used on Symbian.} + + Specifies which platform capabilities the application should have. For more + information, please refer to the S60 SDK documentation. + + \target TARGET.EPOCALLOWDLLDATA + \section1 TARGET.EPOCALLOWDLLDATA + + \e {This is only used on Symbian.} + + Specifies whether static data should be allowed in the application. Symbian + disallows this by default in order to save memory. To use it, set this to 1. + + \target TARGET.EPOCHEAPSIZE + \section1 TARGET.EPOCHEAPSIZE + + \e {This is only used on Symbian.} + + Specifies the minimum and maximum heap size of the application. The program + will refuse to run if the minimum size is not available when it starts. For + example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 135 + + \target TARGET.EPOCSTACKSIZE + \section1 TARGET.EPOCSTACKSIZE + + \e {This is only used on Symbian.} + + Specifies the maximum stack size of the application. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 136 + + \target TARGET.SID + \section1 TARGET.SID + + \e {This is only used on Symbian.} + + Specifies which secure identifier to use for the target application or + library. For more information, see the S60 SDK documentation. + + \target TARGET.UID2 + \section1 TARGET.UID2 + + \e {This is only used on Symbian.} + + Specifies which unique identifier 2 to use for the target application or + library. If this variable is not specified, it defaults to the same value + as TARGET.UID3. For more information, see the S60 SDK documentation. + + \target TARGET.UID3 + \section1 TARGET.UID3 + + \e {This is only used on Symbian.} + + Specifies which unique identifier 3 to use for the target application or + library. If this variable is not specified, a UID3 suitable for development + and debugging will be generated automatically. However, applications being + released should always define this variable. For more information, see the + S60 SDK documentation. + + \target TARGET.VID + \section1 TARGET.VID + + \e {This is only used on Symbian.} + + Specifies which vendor identifier to use for the target application or + library. For more information, see the S60 SDK documentation. + \section1 TARGET_EXT This variable specifies the target's extension. The value of this variable @@ -3447,22 +3801,70 @@ \table \header - \o Member - \o Description - \row - \o combine - \o Indicates that all of the input files are combined into a single output file. - \row - \o target_predeps - \o Indicates that the output should be added to the list of PRE_TARGETDEPS. - \row - \o explicit_dependencies - \o The dependencies for the output only get generated from the depends member and from - nowhere else. - \row - \o no_link - \o Indicates that the output should not be added to the list of objects to be linked in - \endtable + \o Member + \o Description + \row + \o commands + \o The commands used for for generating the output from the input. + \row + \o CONFIG + \o Specific configuration options for the custom compiler. See the CONFIG table for details. + \row + \o depend_command + \o Specifies a command used to generate the list of dependencies for the output. + \row + \o dependency_type + \o Specifies the type of file the output is, if it is a known type (such as TYPE_C, + TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. + \row + \o depends + \o Specifies the dependencies of the output file. + \row + \o input + \o The variable that contains the files that should be processed with the custom compiler. + \row + \o name + \o A description of what the custom compiler is doing. This is only used in some backends. + \row + \o output + \o The filename that is created from the custom compiler. + \row + \o output_function + \o Specifies a custom qmake function that is used to specify the filename to be created. + \row + \o variables + \o Indicates that the variables specified here are replaced with $(QMAKE_COMP_VARNAME) when refered to + in the pro file as $(VARNAME). + \row + \o variable_out + \o The variable that the files created from the output should be added to. + \endtable + + List of members specific to the CONFIG option: + + \table + \header + \o Member + \o Description + \row + \o combine + \o Indicates that all of the input files are combined into a single output file. + \row + \o target_predeps + \o Indicates that the output should be added to the list of PRE_TARGETDEPS. + \row + \o explicit_dependencies + \o The dependencies for the output only get generated from the depends member and from + nowhere else. + \row + \o no_link + \o Indicates that the output should not be added to the list of objects to be linked in. + \endtable + + \note Symbian specific: Generating objects to be linked in is not supported in Symbian, + so either the \c CONFIG option \c no_link or variable \c variable_out + should always be defined for extra compilers. + */ /*! diff --git a/doc/src/examples/htmlinfo.qdoc b/doc/src/examples/htmlinfo.qdoc new file mode 100644 index 000000000..68e83200d --- /dev/null +++ b/doc/src/examples/htmlinfo.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/htmlinfo + \title XML HTML Info Example + + The XML HTML Info example provides a simple command line utility that + scans the current directory for HTML files and prints statistics about + them to standard out. + + \note Standard out is redirected on some platforms. On Symbian using Open + C \c stdout is by default directed to the console window, but this window + may not always be visible. To redirect to a file instead, locate the \c + c:\\system\\data\\config.ini file (on either the emulator or the device) + and change \c STDOUT to point to \c MEDIA4. This will redirect the console + to \c c:\\system\\data\\out.txt. + + The files are parsed using a QXmlStreamReader object. If the file does + not contain a well-formed XML document, a description of the error is + printed to the standard error console. + + \section1 Basic Operation + + The main function of the example uses QDir to access files in the current + directory that match either "*.htm" or "*.html". For each file found, + the \c parseHtmlFile() function is called. + + Reading XML is handled by an instance of the QXmlStreamReader class, which + operates on the input file object: + + \snippet examples/xml/htmlinfo/main.cpp 0 + + The work of parsing and the XML and extracting statistics is done in a + while loop, and is driven by input from the reader: + + \snippet examples/xml/htmlinfo/main.cpp 1 + + If more input is available, the next token from the input file is read + and parsed. The program then looks for the specific element types, + "title", "a", and "p", and stores information about them. + + When there is no more input, the loop terminates. If an error occurred, + information is written to the standard out file via a stream, and the + example exits: + + \snippet examples/xml/htmlinfo/main.cpp 2 + + If no error occurred, the example prints some statistics from the data + gathered in the loop, and then exits. +*/ diff --git a/doc/src/exceptionsafety.qdoc b/doc/src/exceptionsafety.qdoc new file mode 100644 index 000000000..284159feb --- /dev/null +++ b/doc/src/exceptionsafety.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page exceptionsafety.html + \title Exception Safety + \ingroup architecture + \brief A guide to exception safety in Qt. + + \bold {Preliminary warning}: Exception safety is not feature complete! + Common cases should work, but classes might still leak or even crash. + + Qt itself will not throw exceptions. Instead, error codes are used. + In addition, some classes have user visible error messages, for example + \l QIODevice::errorString() or \l QSqlQuery::lastError(). + This has historical and practical reasons - turning on exceptions + can increase the library size by over 20%. + + The following sections describe Qt's behavior if exception support is + enabled at compile time. + + \tableofcontents + + \section1 Exception safe modules + + \section2 Containers + + Qt's \l{container classes} are generally exception neutral. They pass any + exception that happens within their contained type \c T to the user + while keeping their internal state valid. + + Example: + + \code + QList<QString> list; + ... + try { + list.append("hello"); + } catch (...) { + } + // list is safe to use - the exception did not affect it. + \endcode + + Exceptions to that rule are containers for types that can throw during assignment + or copy constructions. For those types, functions that modify the container as well as + returning a value, are unsafe to use: + + \code + MyType s = list.takeAt(2); + \endcode + + If an exception occurs during the assignment of \c s, the value at index 2 is already + removed from the container, but hasn't been assigned to \c s yet. It is lost + without chance of recovery. + + The correct way to write it: + + \code + MyType s = list.at(2); + list.removeAt(2); + \endcode + + If the assignment throws, the container still contains the value, no data loss occured. + + Note that implicitly shared Qt classes will not throw in their assignment + operators or copy constructors, so the limitation above does not apply. + + \section1 Out of Memory Handling + + Most desktop operating systems overcommit memory. This means that \c malloc() + or \c{operator new} return a valid pointer, even though there is not enough + memory available at allocation time. On such systems, no exception of type + \c std::bad_alloc is thrown. + + On all other operating systems, Qt will throw an exception of type std::bad_alloc + if any allocation fails. Allocations can fail if the system runs out of memory or + doesn't have enough continuous memory to allocate the requested size. + + Exceptions to that rule are documented. As an example, \l QImage::create() + returns false if not enough memory exists instead of throwing an exception. + + \section1 Recovering from exceptions + + Currently, the only supported use case for recovering from exceptions thrown + within Qt (for example due to out of memory) is to exit the event loop and do + some cleanup before exiting the application. + + Typical use case: + + \code + QApplication app(argc, argv); + ... + try { + app.exec(); + } catch (const std::bad_alloc &) { + // clean up here, e.g. save the session + // and close all config files. + + return 0; // exit the application + } + \endcode + + After an exception is thrown, the connection to the windowing server + might already be closed. It is not safe to call a GUI related function + after catching an exception. + + \section1 Platform-Specific Exception Handling + + \section2 Symbian (Qt for S60) + + The Symbian platform implements its own exception system that differs from the standard + C++ mechanism. When using Qt for S60, and especially when writing code to access Symbian + functionality directly, it may be necessary to know about the underlying implementation + and how it interacts with Qt. + + The \l{Exception Safety with Symbian} document shows how to use the facilities provided + by Qt to use exceptions as safely as possible. +*/ diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc index 10791d827..9bf774bb8 100644 --- a/doc/src/getting-started/installation.qdoc +++ b/doc/src/getting-started/installation.qdoc @@ -497,6 +497,146 @@ in the \l{Qt for Windows CE Requirements} document. We hope you will enjoy using Qt. Good luck! */ +/*! \page install-S60-installer.html + +\title Installing Qt on S60 using binary package +\ingroup qts60 +\brief How to install Qt on S60 using the binary package. + +\note Qt for S60 has some requirements that are given in more detail +in the \l{Qt for S60 Requirements} document. + +\list 1 + + \o Install Qt + + Run \c{qt-s60-%VERSION%.exe} and follow the instructions. + + \note Qt must be installed on the same drive as the S60 SDK you are + using, and the install path must not contain any spaces. + + \o 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, you first have to install + \c{qt_libs.sis} and \c{fluidlauncher.sis} found in the Qt installation + directory. Begin by connecting your phone using the USB cable and + selecting "PC Suite mode". In Windows Explorer right click on the + \c{.sis} files and select "Install with Nokia Application Installer" + and follow the instructions. + + To run the demos and examples on the emulator, you need to build them first. + Open the "Qt for S60 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 S60, + see \l{S60 - Introduction to using Qt}. + + We hope you will enjoy using Qt. + +\endlist + +*/ +/*! \page install-S60.html + +\title Installing Qt on S60 +\ingroup installation +\ingroup qts60 +\brief How to install Qt on S60 + +\note Qt for S60 has some requirements that are given in more detail +in the \l{Qt for S60 Requirements} document. + +\note \bold {This document describes how to install and configure Qt for S60 from scratch. +If you are using pre-built binaries, follow the instructions +\l{Installing Qt on S60 using binary package}{here}.} + +\list 1 + + \o Install Qt + + Uncompress the package into the directory you want Qt installed, + e.g. \c{C:\Qt\%VERSION%}. + + \note Qt must be installed on the same drive as the S60 SDK you are + using, and the install path must not contain any spaces. + + \o Environment variables + + In order to build and use Qt, the \c PATH environment variable needs + to be extended: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 18 + + This is done by adding \c{c:\Qt\%VERSION%\bin} to the \c PATH variable. + + On Windows the PATH can be extended by navigating to + "Control Panel->System->Advanced->Environment variables". + + In addition, you must configure the environment for use with the S60 + emulator. This is done by locating the Carbide.c++ submenu on the Start + menu, and choosing "Configure environment for WINSCW command line". + + \o Configure Qt + + To configure Qt for S60, do: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 23 + + For other options, type \c{configure -help} to get a list of all available + options. + + \o Build Qt + + To build Qt for the device, type: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 28 + + To build Qt for the emulator, type: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 24 + + Congratulations, Qt is now ready to use. + + \o 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, you first have to install + the Qt libraries on the device: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 29 + + \note You will need to supply certificate that allows installation + of binaries with "All -Tcb" capability to your device. + + Similarly, install fluidlauncher to the device: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 30 + + This will create a self-signed \c fluidlauncher_armv5_urel.sis and + install it to your device. + + 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 S60, + see \l{S60 - Introduction to using Qt}. + + We hope you will enjoy using Qt. + +\endlist + +*/ /*! \page requirements.html \title General Qt Requirements @@ -523,6 +663,7 @@ in the \l{Qt for Windows CE Requirements} document. \list \o \l{Qt for Embedded Linux Requirements} \o \l{Qt for Mac OS X Requirements} + \o \l{Qt for S60 Requirements} \o \l{Qt for Windows CE Requirements} \o \l{Qt for Windows Requirements} \o \l{Qt for X11 Requirements} @@ -804,3 +945,39 @@ in the \l{Qt for Windows CE Requirements} document. enables the use of the Record extension to the X protocol to be used in applications. */ + +/*! + \page requirements-s60.html + \title Qt for S60 Requirements + \ingroup installation + \brief Setting up the S60 environment for Qt. + \previouspage General Qt Requirements + + Qt for S60 requires the following software installed on your development PC: + \list + \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/carbide_cpp/}{Carbide.c++ v2.0.0 or higher} + \list + \o \bold{Note:} It may be necessary to update the Carbide compiler. + See \l{http://pepper.troll.no/s60prereleases/patches/}{here} for instructions how to check your + compiler version and how to patch it, if needed. + \endlist + \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}{S60 Platform SDK 3rd Edition FP1 or higher} + \o \l{http://www.forum.nokia.com/main/resources/technologies/openc_cpp/}{Open C/C++ v1.6.0 or higher}. + Install this to all S60 SDKs you plan to use Qt with. + \o Building Qt libraries requires \l{http://www.arm.com/products/DevTools/RVCT.html}{RVCT} 2.2 [build 616] or later, + which is not available free of charge. + \endlist + + Running Qt on real device requires the following packages to be installed on your device. + The packages can be found in the S60 SDK where you installed Open C/C++: + \list + \o \c{nokia_plugin\openc\s60opencsis\pips_s60_<version>.sis} + \o \c{nokia_plugin\openc\s60opencsis\openc_ssl_s60_<version>.sis} + \o \c{nokia_plugin\opencpp\s60opencppsis\stdcpp_s60_<version>.sis} + \endlist + + \note Users of \bold{S60 Platform SDK 3rd Edition FP1} also need special updates. The update can be found + \l{http://pepper.troll.no/s60prereleases/patches/}{here}. + + \sa {Known Issues in %VERSION%} +*/ diff --git a/doc/src/howtos/appicon.qdoc b/doc/src/howtos/appicon.qdoc index a664adee9..2452689bd 100644 --- a/doc/src/howtos/appicon.qdoc +++ b/doc/src/howtos/appicon.qdoc @@ -212,4 +212,19 @@ installed in the appropriate locations for GNOME. The GNOME developer website is at \l{http://developer.gnome.org/}. + + \section1 Setting the Application Icon on S60 platforms + + In order to set application icon for S60 application you need SVG-T icon. + How to create such SVG-T, please refer to + \l{http://wiki.forum.nokia.com/index.php/How_to_create_application_icon(SVG)_in_S60_3rd_edition/} + + Once you have icon in correct format and assuming you are using + \c qmake to generate your makefiles, you only need to add a single + line to your \c .pro project file. For example, if the name of your + icon file is \c{myapp.svg}, and your project file is \c{myapp.pro}, + add this line to \c{myapp.pro}: + + \snippet doc/src/snippets/code/doc_src_appicon.qdoc 5 + */ diff --git a/doc/src/platforms/emb-install.qdoc b/doc/src/platforms/emb-install.qdoc index e23cc1b77..9cd3fade4 100644 --- a/doc/src/platforms/emb-install.qdoc +++ b/doc/src/platforms/emb-install.qdoc @@ -42,10 +42,10 @@ /*! \page qt-embedded-install.html - \title Installing Qt for Embedded Linux + \title Installing Qt on Embedded Linux \ingroup qt-embedded-linux \ingroup installation - \brief How to install Qt for Embedded Linux. + \brief How to install Qt on Embedded Linux. This document describes how to install \l{Qt for Embedded Linux} in your development environment: diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc index 20f0933ca..e79b2f4a5 100644 --- a/doc/src/platforms/platform-notes.qdoc +++ b/doc/src/platforms/platform-notes.qdoc @@ -401,6 +401,19 @@ */ /*! + \page platform-notes-symbian.html + \title Platform Notes - Symbian + \contentspage Platform Notes + + This page contains information about the Symbian platforms Qt is currently known + to run on. More information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. + + For information about mixing exceptions with symbian leaves, + see \l{Exception Safety with Symbian} +*/ + +/*! \page platform-notes-embedded-linux.html \title Platform Notes - Embedded Linux \contentspage Platform Notes diff --git a/doc/src/s60-introduction.qdoc b/doc/src/s60-introduction.qdoc new file mode 100644 index 000000000..24f781717 --- /dev/null +++ b/doc/src/s60-introduction.qdoc @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + \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, Qt comes with a tool called + \c createpackage. When used on the \c .pkg files created by qmake, it + will produce a signed \c .sis file that can be installed to the device. For + example: + + \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 2 + + 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 createpackage + with the \c -i switch, like this: + + \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 3 +*/ diff --git a/doc/src/snippets/code/doc_src_appicon.qdoc b/doc/src/snippets/code/doc_src_appicon.qdoc index c8883fe38..c763a685e 100644 --- a/doc/src/snippets/code/doc_src_appicon.qdoc +++ b/doc/src/snippets/code/doc_src_appicon.qdoc @@ -21,3 +21,7 @@ kde-config --path icon //! [4] gnome-config --datadir //! [4] + +//! [5] +ICON = myapp.svg +//! [5] diff --git a/doc/src/snippets/code/doc_src_installation.qdoc b/doc/src/snippets/code/doc_src_installation.qdoc index e35dad9f0..489016d98 100644 --- a/doc/src/snippets/code/doc_src_installation.qdoc +++ b/doc/src/snippets/code/doc_src_installation.qdoc @@ -125,3 +125,41 @@ setcepaths wincewm50pocket-msvc2005 //! [22] nmake //! [22] + + +//! [23] +cd \Qt\%VERSION% +configure -platform win32-mwc -xplatform symbian-abld +//! [23] + + +//! [24] +make debug-winscw +//! [24] + +//! [25] +cd examples +qmake +make +cd ..\demos +qmake +make +//! [25] + +//! [27] +make run +//! [27] + +//! [28] +make release-armv5 +//! [28] + +//! [29] +cd src\s60installs +createpackage -i qt_libs_armv5_urel.pkg <certificate file> <certificate key file> +//! [29] + +//! [30] +cd embedded\fluidlauncher +createpackage -i fluidlauncher_armv5_urel.pkg +//! [30] diff --git a/doc/src/snippets/code/doc_src_qmake-manual.qdoc b/doc/src/snippets/code/doc_src_qmake-manual.qdoc index 82c710d44..64dc559f4 100644 --- a/doc/src/snippets/code/doc_src_qmake-manual.qdoc +++ b/doc/src/snippets/code/doc_src_qmake-manual.qdoc @@ -809,5 +809,122 @@ CONFIG(debug, debug|release) { //! [127] //! [128] -DEPLOYMENT_PLUGIN += qjpeg +customplugin.sources = customimageplugin.dll +customplugin.sources += c:\myplugins\othercustomimageplugin.dll +customplugin.path = imageformats +dynamiclibrary.sources = mylib.dll helper.exe +dynamiclibrary.path = \sys\bin +globalplugin.sources = someglobalimageplugin.dll +globalplugin.path = \resource\qt\plugins\imageformats +DEPLOYMENT += customplugin dynamiclibrary globalplugin //! [128] + +//! [129] +TARGET.EPOCALLOWDLLDATA = 1 +//! [129] + +//! [130] +TARGET.EPOCHEAPSIZE = 10000 10000000 +TARGET.EPOCSTACKSIZE = 0x8000 +//! [130] + +//! [131] +QMAKE_CXXFLAGS.CW += -O2 +QMAKE_CXXFLAGS.ARMCC += -O0 +//! [131] + +//! [132] +TARGET.UID2 = 0x00000001 +TARGET.UID3 = 0x00000002 +TARGET.SID = 0x00000003 +TARGET.VID = 0x00000004 +//! [132] + +//! [133] +TARGET.CAPABILITY += AllFiles +//! [133] + +//! [134] +TARGET.CAPABILITY = ALL -TCB +//! [134] + +//! [135] +TARGET.EPOCHEAPSIZE = 10000 10000000 +//! [135] + +//! [136] +TARGET.EPOCSTACKSIZE = 0x8000 +//! [136] + +//! [137] +MMP_RULES += "DEFFILE hello.def" +//! [137] + +//! [138] +myBlock = \ +"START RESOURCE foo.rss" \ +"TARGET bar" \ +"TARGETPATH private\10001234" \ +"HEADER" \ +"LANG 01" \ +"UID 0x10002345 0x10003456" \ +"END" + +MMP_RULES += myBlock +//! [138] + +//! [139] +myIfdefBlock = \ +"$${LITERAL_HASH}ifdef WINSCW" \ +"DEFFILE hello_winscw.def" \ +"$${LITERAL_HASH}endif" + +MMP_RULES += myIfdefBlock +//! [139] + +//! [140] +somelib.sources = somelib.dll +somelib.path = \sys\bin +somelib.pkg_prerules = "(0x12345678), 2, 2, 0, {\"Some Package\"}" \ + "(0x87654321), 1, *, * ~ 2, 2, 0, {\"Some Other Package\"}" +justdep.pkg_prerules = "(0xAAAABBBB), 0, 2, 0, {\"My Framework\"}" +DEPLOYMENT += somelib justdep +//! [140] + +//! [141] +default_deployment.pkg_prerules = "[0x11223344],0,0,0,{\"SomeSpecificDeviceID\"}" +//! [141] + +//! [142] +DEPLOYMENT_PLUGIN += qjpeg +//! [142] + +//! [143] +myextension = \ + "start extension myextension" \ + "$${LITERAL_HASH}if defined(WINSCW)" \ + "option MYOPTION foo" \ + "$${LITERAL_HASH}endif" \ + "option MYOPTION bar" \ + "end" +BLD_INF_RULES.prj_extensions += myextension +//! [143] + +//! [144] +RSS_RULES += "hidden = KAppIsHidden;" +//! [144] + +//! [145] +myrssrules = \ + "hidden = KAppIsHidden;" \ + "launch = KAppLaunchInBackground;" \ +RSS_RULES += myrssrules +//! [145] + +//! [146] +BLD_INF_RULES.prj_exports += \ + "$${LITERAL_HASH}include <platform_paths.hrh>" \ + "rom/my.iby APP_LAYER_PUBLIC_EXPORT_PATH(my.iby)" \ + "inc/myheader.h mycomp/myheader.h" \ + ":zip my_api.zip my_api" +//! [146] diff --git a/doc/src/snippets/code/doc_src_s60-introduction.qdoc b/doc/src/snippets/code/doc_src_s60-introduction.qdoc new file mode 100644 index 000000000..ff1d159c2 --- /dev/null +++ b/doc/src/snippets/code/doc_src_s60-introduction.qdoc @@ -0,0 +1,16 @@ +//! [0] + qmake +//! [0] + + +//! [1] + make debug-winscw +//! [1] + +//! [2] + createpackage wiggly_gcce_udeb.pkg +//! [2] + +//! [3] + createpackage -i wiggly_gcce_udeb.pkg +//! [3] diff --git a/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp b/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp new file mode 100644 index 000000000..b625eb225 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp @@ -0,0 +1,103 @@ +//! [0] +void myFunction(bool useSubClass) +{ + MyClass *p = useSubClass ? new MyClass() : new MySubClass; + QIODevice *device = handsOverOwnership(); + + if (m_value > 3) { + delete p; + delete device; + return; + } + + try { + process(device); + } + catch (...) { + delete p; + delete device; + throw; + } + + delete p; + delete device; +} +//! [0] + +//! [1] +void myFunction(bool useSubClass) +{ + // assuming that MyClass has a virtual destructor + QScopedPointer<MyClass> p(useSubClass ? new MyClass() : new MySubClass); + QScopedPointer<QIODevice> device(handsOverOwnership()); + + if (m_value > 3) + return; + + process(device); +} +//! [1] + +//! [2] + const QWidget *const p = new QWidget(); + // is equivalent to: + const QScopedPointer<const QWidget> p(new QWidget()); + + QWidget *const p = new QWidget(); + // is equivalent to: + const QScopedPointer<QWidget> p(new QWidget()); + + QWidget *const p = new QWidget(); + // is equivalent to: + const QScopedPointer<QWidget> p(new QWidget()); + + const QWidget *p = new QWidget(); + // is equivalent to: + QScopedPointer<const QWidget> p(new QWidget()); + +//! [2] + +//! [3] +if (scopedPointer) { + ... +} +//! [3] + +//! [4] +class MyPrivateClass; // forward declare MyPrivateClass + +class MyClass +{ +private: + QScopedPointer<MyPrivateClass> privatePtr; // QScopedPointer to forward declared class + +public: + MyClass(); // OK + inline ~MyClass() {} // VIOLATION - Destructor must not be inline + +private: + Q_DISABLE_COPY(MyClass) // OK - copy constructor and assignment operators + // are now disabled, so the compiler won't implicitely + // generate them. +}; +//! [4] + +//! [5] +// this QScopedPointer deletes its data using the delete[] operator: +QScopedPointer<int, QScopedPointerArrayDeleter<int> > arrayPointer(new int[42]); + +// this QScopedPointer frees its data using free(): +QScopedPointer<int, QScopedPointerPodDeleter<int> > podPointer(reinterpret_cast<int *>(malloc(42))); + +// this struct calls "myCustomDeallocator" to delete the pointer +struct ScopedPointerCustomDeleter +{ + static inline void cleanup(MyCustomClass *pointer) + { + myCustomDeallocator(pointer); + } +}; + +// QScopedPointer using a custom deleter: +QScopedPointer<MyCustomClass, ScopedPointerCustomDeleter> customPointer(new MyCustomClass); +//! [5] diff --git a/doc/src/symbian-exceptionsafety.qdoc b/doc/src/symbian-exceptionsafety.qdoc new file mode 100644 index 000000000..9183ba79e --- /dev/null +++ b/doc/src/symbian-exceptionsafety.qdoc @@ -0,0 +1,241 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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 +*/ |