diff options
author | Geir Vattekar <geir.vattekar@nokia.com> | 2011-02-24 17:31:18 (GMT) |
---|---|---|
committer | Geir Vattekar <geir.vattekar@nokia.com> | 2011-02-24 17:31:18 (GMT) |
commit | 5b447dfb035c18b05341358f2c43951f33ded3e5 (patch) | |
tree | 20e666bfe8e97ea80bf6426f46965479cd7b8f99 /doc | |
parent | 8845da82b109b8dd93d7461d01e7ce84a8f49a04 (diff) | |
parent | fcea2461489fd392975f8393d7dde8dc1bb6542d (diff) | |
download | Qt-5b447dfb035c18b05341358f2c43951f33ded3e5.zip Qt-5b447dfb035c18b05341358f2c43951f33ded3e5.tar.gz Qt-5b447dfb035c18b05341358f2c43951f33ded3e5.tar.bz2 |
Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-doc-team into 4.7
Diffstat (limited to 'doc')
-rw-r--r-- | doc/src/declarative/basictypes.qdoc | 178 | ||||
-rw-r--r-- | doc/src/declarative/modules.qdoc | 194 | ||||
-rw-r--r-- | doc/src/getting-started/installation.qdoc | 23 | ||||
-rw-r--r-- | doc/src/internationalization/linguist-manual.qdoc | 282 | ||||
-rw-r--r-- | doc/src/platforms/platform-notes.qdoc | 6 | ||||
-rw-r--r-- | doc/src/snippets/code/doc_src_installation.qdoc | 7 | ||||
-rw-r--r-- | doc/src/sql-programming/sql-driver.qdoc | 4 |
7 files changed, 378 insertions, 316 deletions
diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 02cd31a..cd10e2b 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -405,8 +405,6 @@ \qml Item { - property variant values: [ 10, 20, 'abc', 'xyz' ] - property list<Rectangle> rects: [ Rectangle { width: 100; height: 100}, Rectangle { width: 200; height: 200} @@ -414,136 +412,124 @@ } \endqml - A \c variant list can contain values of any of the \l {QML Basic Types}{basic QML types} - such as numbers, strings, etc. while a \c list<Type> list can only contain values - that match (or are derived from) the specified \c Type. + A list property can only contain values that match (or are derived from) the + specified \c Type. - A list property can be cleared by setting it to an empty list: + While the \c rects property can be reassigned to a different list value (including + an empty list), its individual values cannot be modified. See the \l variant type + documentation for details. - \qml - Item { - children: [] - } - \endqml + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype variant + \ingroup qmlbasictypes - A list property cannot be modified in any other way. Items cannot be dynamically added to - or removed from the list through JavaScript operations; any \c push() operations on the - list only modify a \e copy of the list and not the actual list. (These current limitations - are due to restrictions on \l {Property Binding} where lists are involved.) + \brief A variant type is a generic property type. - You can, however, modify a copy of the list and then reassign the property to the modified - value. Other options are to create an array object from within a \c .js JavaScript file, - or implement a custom list element in C++. Here is a QML element that modifies the list in a - JavaScript file: + A variant is a generic property type. A variant type property can hold + any of the \l {QML Basic Types}{basic type} values: - \table - \row - \o \qml - // QML - import "script.js" as Script - Item { - Component.onCompleted: { - Script.addItem('abc') - console.log("Added:", Script.getList()[0]) - } + property variant aNumber: 100 + property variant aString: "Hello world!" + property variant aBool: false } \endqml - \o - \code - // script.js - var myArray = new Array() + The \c variant type can also hold: - function getList() { - return myArray - } - - function addItem(item) { - myArray.push(item) - } - \endcode - \endtable - - However, note that a JavaScript list should not be used as a QML \c property value, - as the property is not updated when the list changes. + \list + \o An array of \l {QML Basic Types}{basic type} values + \o A map of key-value pairs with \l {QML Basic Types}{basic-type} values + \endlist - \sa {QML Basic Types} -*/ + For example, below is an \c items array and an \c attributes map. Their + contents can be examined using JavaScript \c for loops. Individual array + values are accessible by index, and individual map values are accessible + by key: + \qml + Item { + property variant items: [1, 2, 3, "four", "five"] + property variant attributes: { 'color': 'red', 'width': 100 } -/*! - \qmlbasictype variant - \ingroup qmlbasictypes + Component.onCompleted: { + for (var i=0; i<items.length; i++) + console.log(items[i]) - \brief A variant type is a generic property type. + for (var prop in attributes) + console.log(prop, "=", attributes[prop]) + } + } + \endqml - A variant is a generic property type. A variant type property can hold any of the - \l {QML Basic Types}{basic type} values: + While this is a convenient way to store array and map-type values, you + must be aware that the \c items and \c attributes properties above are \e not + QML objects (and certainly not JavaScript object either) and the key-value + pairs in \c attributes are \e not QML properties. Rather, the \c items + property holds an array of values, and \c attributes holds a set of key-value + pairs. Since they are stored as a set of values, instead of as an object, + their contents \e cannot be modified individually: \qml Item { - property variant aNumber : 100 - property variant aString : "Hello world!" - property variant aList : [ 1, 2, "buckle my shoe" ] + property variant items: [1, 2, 3, "four", "five"] + property variant attributes: { 'color': 'red', 'width': 100 } + + Component.onCompleted: { + items[0] = 10 + console.log(items[0]) // This will still be '1'! + attributes.color = 'blue' + console.log(attributes.color) // This will still be 'red'! + } } \endqml - The \c variant type can also hold a \e copy of a JavaScript object. For example, the - \c animal property below defines a JavaScript object defined with JSON notation. The - object's properties and values can be examined using the standard JavaScript syntax, - as shown in the \c Component.onCompleted handler. + Additionally, since \c items and \c attributes are not QML objects, changing + their individual values do not trigger property change notifications. If + the above example had \c onNumberChanged or \c onAnimalChanged signal + handlers, they would not have been called. If, however, the \c items or + \c attributes properties themselves were reassigned to different values, then + such handlers would be called. + + One way to "update" the contents of an array or map is to copy the property + to a JavaScript object, modify the copy as desired, and then reassign the + property to the updated copy. Note, however, that this is not efficient. + In the example below, which reassigns the \c attributes property, the \e entire + set of key-value pairs must be serialized and deserialized every time it is + copied between a JavaScript object and a QML property: \qml Item { - property variant animal : { 'type': 'bird', 'species': 'galah', 'age': 7 } + property variant attributes: { ''color': 'red', 'width': 100 } Component.onCompleted: { - for (var attribute in animal) - console.log(attribute, "=", animal[attribute]) + // Change the value of attributes.color to 'blue': + var temp = attributes // copy all values to 'temp' + temp.color = 'blue' + attributes = temp // copy all values back to 'attributes' } } \endqml - It must be noted that the \c animal property holds a \e copy of the defined object, and - not the object itself. (This is true even if the property refers to an object defined in - some JavaScript file; the property will hold a copy of the object, and not the actual - object.) The property essentially holds a copy of the contents within the object. This - has several implications: + Since this operation is inefficient, if a list or map should be modifiable, + it is better to use alternative approaches. For example, you could implement + a custom C++ list element, or write to a JavaScript object defined from + within a JavaScript file. - \list - \o Changes to any of the property's values (for example, the \c animal.type value - above) only modify the \e copy of the object, not the object itself. You can, however, - modify a copy of the object and then reassign the property to the modified value. - \o Because the property only holds a copy of the object, \l{Property Binding}{bindings} to - any of the property's individual values are not updated until the whole property is - reassigned to a new value. For example: - - \qml - Item { - property variant animal : { 'type': 'bird', 'species': 'galah', 'age': 7 } - - Text { text: "Animal species: " + animal.species } - - Component.onCompleted: { - animal.species = 'kookaburra' // this has no effect on the displayed text - - var newObj = animal - newObj.species = 'kookaburra' - animal = newObj // this will update the displayed text - } - } - \endqml - \o Since the object values are copied, it does not hold any reference to the original - object, and extra data such as the object's JavaScript prototype chain is lost in the - process. - \endlist + JavaScript programmers should also note that when a JavaScript object is + copied to an array or map property, the \e contents of the object (that is, + its key-value properties) are copied, rather than the object itself. The + property does not hold a reference to the original JavaScript object, and + extra data such as the object's JavaScript prototype chain is also lost in + the process. \sa {QML Basic Types} */ - /*! \qmlbasictype vector3d \ingroup qmlbasictypes diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index 3bb69da..f1ebd00 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -44,7 +44,7 @@ example, an \c import statement is required to use: \list \o A component defined in another QML file that is not in the same directory \o A component defined in a QML file located on a remote server -\o A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} library (unless the plugin is installed in the same directory) +\o A \l{QDeclarativeExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory) \o A JavaScript file (note this must be imported using \l {#namespaces}{named imports}) \endlist @@ -61,12 +61,12 @@ are not included in the global namespace by default.) The \c Qt module is an \e installed module; it is found in the \l{The QML import path}{import path}. There are two types of QML modules: -location modules (defined by a URL) and installed modules (defined by a URI). +located modules (defined by a URL) and installed modules (defined by a URI). -\section1 Location Modules +\section1 Located Modules -Location modules can reside on the local filesystem or a network resource, +Located modules can reside on the local filesystem or a network resource, and are referred to by a quoted location URL that specifies the filesystem or network URL. They allow any directory with QML content to be imported as a module, whether the directory is on the local filesystem or a remote @@ -86,8 +86,9 @@ directory using a relative or absolute path, like this: \code MyQMLProject |- MyComponents - |- Slider.qml |- CheckBox.qml + |- Slider.qml + |- Window.qml |- Main |- application.qml \endcode @@ -96,8 +97,10 @@ MyQMLProject \code import "../MyComponents" -Slider { ... } -CheckBox { ... } +Window { + Slider { ... } + CheckBox { ... } +} \endcode \endtable @@ -106,23 +109,51 @@ Similarly, if the directory resided on a network source, it could be imported like this: \code - import "https://qml.nokia.com/qml/qmlcomponents" - import "https://qml.nokia.com/qml/qmlcomponents" 1.0 + import "http://www.my-server.com/MyQMLProject/MyComponents" + import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0 \endcode -Remote location modules must have a \l{Writing a qmldir file}{qmldir file} in the -same directory to specify which QML files should be made available. See the -\l {#qmldirexample}{example} below. The qmldir file is optional for modules on -the local filesystem. +A located module can also be imported as a network resource if it has a +\l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files +to be made available by the module. For example, if the \c MyComponents directory +contained a \c qmldir file defined like this: +\code +Slider 1.0 Slider.qml +CheckBox 1.0 CheckBox.qml +Window 1.0 Window.qml +\endcode + +If the \c MyComponents directory was then hosted as a network resource, it could +be imported as a module, like this: + +\code +import "http://the-server-name.com/MyQMLProject/MyComponents" + +Window { + Slider { ... } + CheckBox { ... } +} +\endcode + +with an optional "1.0" version specification. Notice the import would fail if +a later version was used, as the \c qmldir file specifies that these elements +are only available in the 1.0 version. + +Note that modules imported as a network resource allow only access to components +defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins} +are not available. \section1 Installed modules +Installed modules are modules that are made available through the QML import path, +as defined by QDeclarativeEngine::importPathList(), or modules defined within +C++ application code. An installed module is referred to by a URI, which allows +the module to be imported from QML code without specifying a complete filesystem +path or network resource URL. -Installed modules are modules that are installed on the -local filesystem within the QML import path, or modules defined in C++ -application code. When importing an installed module, an un-quoted URI is +When importing an installed module, an un-quoted URI is used, with a mandatory version number: \code @@ -130,15 +161,23 @@ used, with a mandatory version number: import com.nokia.qml.mymodule 1.0 \endcode -Installed modules that are installed into the import path or created -as a \l{QDeclarativeExtensionPlugin}{QML C++ plugin} must define a -\l{Writing a qmldir file}{qmldir file}. - +When a module is imported, the QML engine searches the QML import path for a matching +module. The root directory of the module must contain a +\l{Writing a qmldir file}{qmldir file} that defines the QML files +and/or C++ QML extension plugins that are made available to the module. -\section2 The QML import path +Modules that are installed into the import path translate the URI into +directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule +must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the +QML import path. In addition it is possible to store different versions of the +module in subdirectories of its own. For example, a version 2.1 of the +module could be located under \c com/nokia/qml/mymodule.2/qmldir or +\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load +the module which matches best. -The QML engine will search the import path for a requested installed module. -The default import path includes: +The import path, as returned by QDeclarativeEngine::importPathList(), defines the default +locations to be searched by the QML engine for a matching module. By default, this list +contains: \list \o The directory of the current file @@ -146,30 +185,80 @@ The default import path includes: \o Paths specified by the \c QML_IMPORT_PATH environment variable \endlist -The import path can be queried using QDeclarativeEngine::importPathList() and modified using QDeclarativeEngine::addImportPath(). +Additional import paths can be added through QDeclarativeEngine::addImportPath() or the +\c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, you +can also use the \c -I option to add an import path. + + +\section2 Creating installed modules + +As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example} +was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents +subdirectory could be made available as an installed module by adding a +\l{Writing a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this: + +\code +Slider 1.0 Slider.qml +CheckBox 1.0 CheckBox.qml +Window 1.0 Window.qml +\endcode + +Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously, +a QML file located anywhere on the local filesystem can then import the module as shown below, +without referring to the module's absolute filesystem location: + +\qml +import projects.MyQMLProject.MyComponents 1.0 + +Window { + Slider { ... } + CheckBox { ... } +} +\endqml + +Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted +as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above +QML code would work just the same. -When running the \l {QML Viewer}, use the \c -I option to add paths to the import path. +Note that modules imported as a network resource allow only access to components +defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins} +are not available. \section2 Creating installed modules in C++ -C++ applications can dynamically define installed modules using -qmlRegisterType(). +C++ applications can define installed modules directly within the application using qmlRegisterType(). +For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial} +defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType(): -For \l{QDeclarativeExtensionPlugin}{QML C++ plugins}, the -module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). -The QDeclarativeExtensionPlugin documentation shows how to use this URI -to call qmlRegisterType() to enable the plugin library to be built as -an installed module. Once the plugin is built and installed, the module is importable -in QML, like this: +\qml +qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart"); +\endqml + +This allows the application's QML files to use the \c PieChart type by importing the declared +\c Charts module: + +\qml +import Charts 1.0 +\endqml + +For \l{QDeclarativeExtensionPlugin}{QML plugins}, the +module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). This method +can be reimplemented by the developer to register the necessary types for the module. Below is the +\c registerTypes() implementation from the \l{declarative/cppextensions/plugins}{QML plugins} +example: + +\snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin + +Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file}, +the module can be imported from QML, like this: \code import com.nokia.TimeExample 1.0 \endcode -A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} also requires a -\l{Writing a qmldir file}{qmldir file} to make it available to the -QML engine. +Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by +a module that is imported as a network resource. @@ -224,7 +313,7 @@ Unlike ordinary modules, multiple scripts cannot be imported into the same names A \c qmldir file is a metadata file for a module that maps all type names in the module to versioned QML files. It is required for installed modules, and -location modules that are loaded from a network source. +located modules that are loaded from a network source. It is defined by a plain text file named "qmldir" that contains one or more lines of the form: @@ -274,37 +363,6 @@ containing the plugin file. By default the engine searches for the plugin librar file. The plugin search path can be queried with QDeclarativeEngine::pluginPathList() and modified using QDeclarativeEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path. -\target qmldirexample -\section2 Example - -If the components in the \c MyComponents directory from the -\l{Location Modules}{earlier example} were to be made available as a network resource, -the directory would need to contain a \c qmldir file similar to this: - -\code -ComponentA 1.0 ComponentA.qml -ComponentB 1.0 ComponentB.qml -\endcode - -The \c MyComponents directory could then be imported as a module using: - -\code -import "http://the-server-name.com/MyComponents" - -Slider { ... } -CheckBox { ... } -\endcode - -with an optional "1.0" version specification. Notice the import fails if -a later version is used, as the \c qmldir file specifies that these elements -are only available in the 1.0 version. - - -For examples of \c qmldir files for plugins, see the -\l {declarative/cppextensions/plugins}{Plugins} example and -\l {Tutorial: Writing QML extensions with C++}. - - \section1 Debugging The \c QML_IMPORT_TRACE environment variable can be useful for debugging diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc index 2e93367..26ccf88 100644 --- a/doc/src/getting-started/installation.qdoc +++ b/doc/src/getting-started/installation.qdoc @@ -874,9 +874,10 @@ If the installation fails, please make sure that there is no previously installed version of Qt on the phone. Qt requires some dependent packages to be installed on the device, -they are shipped in the Symbian SDK and can be installed using the -runonphone tool as well. -The packages can be found in the EPOCROOT at the following locations; +which can be installed using the runonphone tool as well. One is +the \c{sqlite3.sis}, which is included in the Qt distribution, while +the others are shipped with the Symbian SDK. The required packages +can be found from the following locations: \snippet doc/src/snippets/code/doc_src_installation.qdoc 50 @@ -1332,10 +1333,18 @@ We hope you will enjoy using Qt. in this release. \endlist - Running Qt on real device requires the Open C to be installed on the device. - The Open C installation packages are embedded into \c{qt_installer.sis}, which is included in - Qt for Symbian binary package. If you are building Qt from scratch, you can find the - required packages in the Symbian SDK where you installed Open C/C++: + Running Qt on real device requires the Open C and sqlite3 to be installed on the device. + These installation packages are embedded into \c{qt_installer.sis}, which is included in + Qt for Symbian binary package. + + If you are building Qt from scratch, you can find the sqlite3 package from + under your Qt installation: + + \list + \o \c{src\s60installs\sqlite3.sis} + \endlist + + The Open C packages you can find in the Symbian 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} diff --git a/doc/src/internationalization/linguist-manual.qdoc b/doc/src/internationalization/linguist-manual.qdoc index 460e10c..54537b3 100644 --- a/doc/src/internationalization/linguist-manual.qdoc +++ b/doc/src/internationalization/linguist-manual.qdoc @@ -46,10 +46,10 @@ at the person with overall responsibility for the release of the application. They will typically coordinate the work of the software engineers and the translator. The chapter describes the - use of two tools. The \l{lupdate} tool is used to synchronize - source code and translations. The \l{lrelease} tool is used to - create run-time translation files for use by the released - application. + use of two tools. The \l{linguist-manager.html#lupdate}{lupdate} + tool is used to synchronize source code and translations. The + \l{linguist-manager.html#lrelease}{lrelease} tool is used to create + run-time translation files for use by the released application. The \l{linguist-translators.html}{Translators} chapter is for translators. It describes the use of the \QL tool. @@ -77,7 +77,7 @@ programmer is able to add additional context information to phrases when necessary. The release manager generates a set of translation files that are produced from the source files and passes these to the - translator. The translator opens the translation files using \QL, + translator. The translator opens the translation files using \QL, enters their translations and saves the results back into the translation files, which they pass back to the release manager. The release manager then generates fast compact versions of these @@ -149,20 +149,16 @@ \previouspage Qt Linguist Manual \nextpage Qt Linguist Manual: Translators - \keyword lupdate - \keyword lrelease - Two tools are provided for the release manager, \l lupdate and \l lrelease. These tools can process \l qmake project files, or operate directly on the file system. \section1 Qt Project Files - The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease} - {lrelease} is by specifying a \c .pro Qt project file. There must - be an entry in the \c TRANSLATIONS section of the project file for - each language that is additional to the native language. A typical - entry looks like this: + The easiest method to use \l lupdate and \l lrelease is by specifying + a \c .pro Qt project file. There must be an entry in the \c TRANSLATIONS + section of the project file for each language that is additional to + the native language. A typical entry looks like this: \snippet examples/linguist/arrowpad/arrowpad.pro 1 @@ -203,7 +199,6 @@ \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 3 - \target lupdate manual \section1 lupdate Usage: \c {lupdate myproject.pro} @@ -238,8 +233,8 @@ can also process Localization Interchange File Format (XLIFF) format files; files in this format typically have file names that end with the \c .xlf suffix. - - \note The minimum supported version for XLIFF format files is + + \note The minimum supported version for XLIFF format files is 1.1. XLIFF 1.0 version files are not supported. Pass the \c -help option to \c lupdate to obtain the list of @@ -271,7 +266,7 @@ are available the application will detect them and use them automatically. - Note that lrelease will only incorporate translations that are + Note that \l lrelease will only incorporate translations that are marked as "finished". Otherwise the original text will be used instead. @@ -285,7 +280,7 @@ Both \l lupdate and \l lrelease may be used with TS translation source files which are incomplete. Missing translations will be replaced with the native language phrases at - runtime. + runtime. */ /*! @@ -315,7 +310,7 @@ arranged around a central \l{The Translation Area} {translation area}. The \l{Context Window} {context list} is normally shown on the left, and the \l{Sources and Forms Window} {source code}, - \l{Strings Window} {string list}, and either the \l{Phrases and + \l{Strings Window} {string list}, and either the \l{Phrases and Guesses Window} {phrases and guesses}, or the \l{Warnings Window} {warnings} are shown above and below the \l{The Translation Area} {translations area}. @@ -331,9 +326,9 @@ \key{tick mark} button on the toolbar, or click the icon to the left of the selected source string in the string list. Repeat this process until all strings in the string list are marked with - \inlineimage linguist-check-on.png + \inlineimage linguist-check-on.png or - \inlineimage linguist-check-warning.png + \inlineimage linguist-check-warning.png . Then select the next context and continue. Translation options are shown in the \l{Phrases and Guesses @@ -389,17 +384,17 @@ that aren't in a subclass of QObject. To the left of the \e{Context} column is a column labeled - \inlineimage linguist-check-obsolete.png + \inlineimage linguist-check-obsolete.png . This column uses the following list of icons to summarize the current translation state for each context: \list - \o \inlineimage linguist-check-on.png + \o \inlineimage linguist-check-on.png All strings in the context have been translated, and all the translations passed the \l{Validation Tests} {validation tests}. - \o \inlineimage linguist-check-warning.png + \o \inlineimage linguist-check-warning.png All strings in the context have been translated or marked as translated, but at least one translation failed the \l{Validation Tests} {validation tests}. @@ -427,19 +422,19 @@ selected. Its \e{Items} entry shows \bold{18/18}, which means it has 18 translatable strings and all 18 strings currently have translations. However, the context has been marked with the - \inlineimage linguist-check-warning.png - icon, which means that at least one of the current translations - failed a \l{Validation Tests} {validation test}. In the - \l{Strings Window} {strings window} to the right, we see that one - of the strings is indeed marked with the - \inlineimage linguist-check-warning.png + \inlineimage linguist-check-warning.png + icon, which means that at least one of the current translations + failed a \l{Validation Tests} {validation test}. In the + \l{Strings Window} {strings window} to the right, we see that one + of the strings is indeed marked with the + \inlineimage linguist-check-warning.png icon. The context window is a dockable window. It can be dragged to another position in the main window, or dragged out of the main window to be a separate window. If you move the context window, \QL remembers the new position and puts the context window there - whenever you start the program. If the context window has been + whenever you start the program. If the context window has been closed, it can be restored by pressing \key{F6}. \section2 Strings Window @@ -475,16 +470,16 @@ \o The source string has a translation (possibly empty); the user has accepted the translation, and the translation passes all the \l{Validation Tests} {validation tests}. If the translation is - empty, the user has chosen to leave it empty. Click the icon to - revoke acceptance of the translation and decrement the number of + empty, the user has chosen to leave it empty. Click the icon to + revoke acceptance of the translation and decrement the number of accepted translations in the \e{Items} column of the \l{Context - Window} {context list} by 1. The state is reset to - \inlineimage linguist-check-off.png + Window} {context list} by 1. The state is reset to + \inlineimage linguist-check-off.png if the string has a translation, or to \inlineimage linguist-check-empty.png - if the string's translation is empty. If \c{lupdate} changes the - contents of a string, its acceptance state is automatically reset - to \inlineimage linguist-check-off.png + if the string's translation is empty. If \c{lupdate} changes the + contents of a string, its acceptance state is automatically reset + to \inlineimage linguist-check-off.png . \row @@ -493,44 +488,44 @@ \o The user has accepted the translation, but the translation does not pass all the \l{Validation Tests} {validation tests}. The validation test failures are shown in the \l{Warnings Window} - {warnings window}. Click the icon to revoke acceptance of the - translation. The state is reset to \inlineimage linguist-danger.png - , and the number of accepted translations in the \e{Items} column - of the \l{Context Window} {context list} is decremented by 1. + {warnings window}. Click the icon to revoke acceptance of the + translation. The state is reset to \inlineimage linguist-danger.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is decremented by 1. \row \o Not Accepted \o \inlineimage linguist-check-off.png - \o The string has a non-empty translation that passes all the - \l{Validation Tests} {validation tests}, but the user has not yet + \o The string has a non-empty translation that passes all the + \l{Validation Tests} {validation tests}, but the user has not yet accepted the translation. Click the icon or press \key{Ctrl+Enter} - to accept the translation. The state is reset to + to accept the translation. The state is reset to \inlineimage linguist-check-on.png - , and the number of accepted translations in the \e{Items} column - of the \l{Context Window} {context list} is incremented by 1. + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is incremented by 1. \row \o No Translation \o \inlineimage linguist-check-empty.png - \o The string does not have a translation. Click the icon to - accept the empty translation anyway. The state is reset to + \o The string does not have a translation. Click the icon to + accept the empty translation anyway. The state is reset to \inlineimage linguist-check-on.png - , and the number of accepted translations in the \e{Items} column + , and the number of accepted translations in the \e{Items} column of the \l{Context Window} {context list} is incremented by 1. \row \o Validation Failures \o \inlineimage linguist-danger.png - \o The string has a translation, but the translation does not - pass all the \l{Validation Tests} {validation tests}. Validation - test failures are shown in the \l{Warnings Window} {warnings} - window. Click on the icon or press \key{Ctrl+Return} to accept - the translation even with validation failures. The state is + \o The string has a translation, but the translation does not + pass all the \l{Validation Tests} {validation tests}. Validation + test failures are shown in the \l{Warnings Window} {warnings} + window. Click on the icon or press \key{Ctrl+Return} to accept + the translation even with validation failures. The state is reset to \inlineimage linguist-check-warning.png - . We recommended editing the translation to fix the causes of + . We recommended editing the translation to fix the causes of the validation failures. The state will reset automatically to \inlineimage linguist-check-off.png - , when all the failures have been fixed. + , when all the failures have been fixed. \row \o Obsolete @@ -558,12 +553,12 @@ If the developer provides a \l{QObject::tr()} {disambiguating comment}, it will appear below the source text area, under the - label \menu{Developer comments}. + label \menu{Developer comments}. Below the source text and optional developer comments are two text entry widgets for the translator, one for entering the translation of the current string, and one for the translator to enter an - optional comment to be read by other translators. + optional comment to be read by other translators. When \l{Translating Multiple Languages Simultaneously} {multiple languages} are being translated, this sequence of fields is @@ -578,7 +573,7 @@ translation(s) will be listed in this window. If the current string is the same as, or similar to, another string that has already been translated, that other string and its translation - will also be listed in this window. + will also be listed in this window. To use a translation from the Phrases and Guesses Window, you can double click the translation, and it will be copied into the @@ -607,7 +602,7 @@ If the source context shows the wrong source line, it probably means the translation file is out of sync with the source files. To re-sync the translation file with the source files, see the - \l{lupdate manual} {lupdate manual}. + \l{linguist-manager.html#lupdate}{lupdate} manual. The Sources and Forms window is a dockable window. If it has been closed, it can be made visible again by pressing the \e{Sources @@ -638,12 +633,12 @@ and you are given an application's Polish translation file and asked to update the application's Japanese translation file. You are more comfortable translating Polish to Japanese than you are - translating English to Japanese. + translating English to Japanese. Below is the UI snapshot shown earlier, but this time with both \e{Polish} and \e{Japanese} translation files loaded. - \image linguist-linguist_2.png + \image linguist-linguist_2.png The first thing to notice is that the \l{The Translation Area} {translation area} has text editing areas for both Polish and @@ -662,18 +657,18 @@ selected in the snapshot shown above. Recall that in the first UI snapshot (Polish only), the numbers for this context were \e{18/18}, meaning 18 translatable strings had been found in the - context, and all 18 strings had accepted translations. In the UI + context, and all 18 strings had accepted translations. In the UI snapshot above, the numbers for the \bold{MessageEditor} context are now \e{1/18}, meaning that both languages have 18 translatable strings for that context, but for Japanese, only 1 of the 18 - strings has an accepted translation. The - \inlineimage linguist-check-off.png + strings has an accepted translation. The + \inlineimage linguist-check-off.png icon in the Japanese column means that at least one string in the - context doesn't have an accepted Japanese translation yet. In fact, - 17 of the 18 strings don't have accepted Japanese translations yet. - We will see \e{18/18} in the \e{Items} column when all 18 strings - have accepted translations for all the loaded translation files, - e.g., both Polish and Japanese in the snapshot. + context doesn't have an accepted Japanese translation yet. In fact, + 17 of the 18 strings don't have accepted Japanese translations yet. + We will see \e{18/18} in the \e{Items} column when all 18 strings + have accepted translations for all the loaded translation files, + e.g., both Polish and Japanese in the snapshot. \section1 Common Tasks @@ -726,7 +721,7 @@ key in the translation text ("File") precede it with an ampersand, e.g. \e{\&File}. If a string to be translated has an ampersand in it, then the translation for that string should also have an - ampersand in it, preferably in front of the same character. + ampersand in it, preferably in front of the same character. The meaning of an Alt key accelerator can be determined from the phrase in which the ampersand is embedded. The translator can @@ -810,7 +805,7 @@ If the translated text is similar to the source text, choose the \e {Copy from source text} entry in the \menu Translation menu (press - \key{Ctrl+B}) which will copy the source text into the + \key{Ctrl+B}) which will copy the source text into the \l{The Translation Area} {translation area}. \QL automatically lists possible translations from any open @@ -839,9 +834,9 @@ A \QL phrase book is a set of source phrases, target (translated) phrases, and optional definitions. Typically one phrase book - will be created per language and family of applications. Phrase books - are used to provide a common set of translations to help ensure consistency. - They can also be used to avoid duplication of effort since the translations + will be created per language and family of applications. Phrase books + are used to provide a common set of translations to help ensure consistency. + They can also be used to avoid duplication of effort since the translations for a family of applications can be produced once in the phrase book. If the translator reaches an non-translated phrase that is the same as a source phrase in a phrase book, \QL will show the @@ -861,25 +856,25 @@ The phrase book contents can be displayed and changed by selecting \menu{Phrase|Edit Phrase Book}, and then activating the phrase book you want to work on. This will pop up the Phrase Book Dialog as shown - in the image above. To add a new phrase click the \gui{New Phrase} - button (or press Alt+N) and type in a new source phrase. Press Tab and - type in the translation. Optionally press Tab and enter a definition -- - this is useful to distinguish different translations of the same source - phrase. This process may be repeated as often as necessary. You can delete + in the image above. To add a new phrase click the \gui{New Phrase} + button (or press Alt+N) and type in a new source phrase. Press Tab and + type in the translation. Optionally press Tab and enter a definition \mdash + this is useful to distinguish different translations of the same source + phrase. This process may be repeated as often as necessary. You can delete a phrase by selecting it in the phrases list and clicking - Remove Phrase. Click the \gui Close button (press Esc) once you've finished + Remove Phrase. Click the \gui Close button (press Esc) once you've finished adding (and removing) phrases. \section2 Shortcuts for Editing Phrase Books You can also create a new phrase book entry directly out of the translation you are working on: Clicking \menu{Phrases|Add to Phrase Book} or pressing - \key{Ctrl+T} will add the source text and the content of the first translation + \key{Ctrl+T} will add the source text and the content of the first translation field to the current phrase book. If multiple phrase books are loaded, you have to specify the phrase book to add the entry to in a dialogue. - If you detect an error in a phrase book entry that is shown in the - \l{Phrases and Guesses Window}, you can also edit it in place by right - clicking on the entry, and selecting \menu{Edit}. After fixing the error + If you detect an error in a phrase book entry that is shown in the + \l{Phrases and Guesses Window}, you can also edit it in place by right + clicking on the entry, and selecting \menu{Edit}. After fixing the error press \key{Return} to leave the editing mode. \section2 Batch Translation @@ -890,7 +885,7 @@ translate source texts that are also in a phrase book. Selecting \menu{Tools|Batch Translation} will show you the batch translation dialog, which let you configure which phrase books to use in what order during the - batch translation process. Furthermore you can set whether only entries + batch translation process. Furthermore you can set whether only entries with no present translation should be considered, and whether batch translated entries should be set to finished (see also \l {String Translation States}). @@ -929,7 +924,7 @@ Forms created by \e{Qt Designer} are stored in special UI files. \QL can make use of these UI files to show the translations done so far on the form itself. This of course requires access to the UI - files during the translation process. Activate + files during the translation process. Activate \menu{Tools|Open/Refresh Form Preview} to open the window shown above. The list of UI files \QL has detected are displayed in the Forms List on the left hand. If the path to the files has changed, you can load @@ -947,17 +942,18 @@ \list \o TS \e {translation source files} \BR are human-readable XML files containing source phrases and their translations. These files are - usually created and updated by \l lupdate and are specific to an - application. + usually created and updated by \l{linguist-manager.html#lupdate}{lupdate} + and are specific to an application. \o \c .xlf \e {XLIFF files} \BR are human-readable XML files that adhere to the international XML Localization Interchange File Format. \QL - can be used to edit XLIFF files generated by other programs. However, for - standard Qt projects, only the TS file format is used. \note The minimum - supported version for XLIFF format files is 1.1. XLIFF 1.0 version files + can be used to edit XLIFF files generated by other programs. However, for + standard Qt projects, only the TS file format is used. \note The minimum + supported version for XLIFF format files is 1.1. XLIFF 1.0 version files are not supported. \o QM \e {Qt message files} \BR are binary files that contain translations used by an application at run-time. These files are - generated by \l lrelease, but can also be generated by \QL. + generated by \l{linguist-manager.html#lrelease}{lrelease}, but can also + be generated by \QL. \o \c .qph \e {Qt phrase book files} \BR are human-readable XML files containing standard phrases and their translations. These files are created and updated by \QL and may be used by any @@ -982,13 +978,15 @@ name, format and/or put in a different location. \o \gui {Release} \BR create a Qt message QM file with the same base name as the current translation source file. The release manager's - command line tool \l lrelease performs the same function on - \e all of an application's translation source files. + command line tool \l{linguist-manager.html#lrelease}{lrelease} + performs the same function on \e all of an application's translation + source files. \o \gui {Release As...} \BR pops up a save as file dialog. The filename entered will be a Qt message QM file of the translation based on the current translation source file. The release manager's - command line tool \l lrelease performs the same function on - \e all of an application's translation source files. + command line tool \l{linguist-manager.html#lrelease}{lrelease} + performs the same function on \e all of an application's translation + source files. \o \gui {Print... Ctrl+P} \BR pops up a print dialog. If you click OK the translation source and the translations will be printed. \o \gui {Exit Ctrl+Q} \BR closes \QL. @@ -1018,10 +1016,10 @@ Source phrases, translations and comments may be searched. \o \gui {Find Next F3} \BR finds the next occurrence of the text that was last entered in the Find dialog. - \o \gui {Search and Translate...} \BR pops up the Search and + \o \gui {Search and Translate...} \BR pops up the Search and Replace Dialog. Use this dialog to translate the same text in multiple items. \o \gui {Translation File Settings...} \BR let you configure the target - language and the country/region of a translation source file. + language and the country/region of a translation source file. \endlist \o \gui {Translation} @@ -1123,7 +1121,7 @@ \o \gui {Manual F1} \BR opens this manual. \o \gui {About Qt Linguist} \BR Shows information about \QL. \o \gui {About Qt} \BR Shows information about \e{Qt}. - \o \gui {What's This? Shift+F1} \BR Click on one item in the main window + \o \gui {What's This? Shift+F1} \BR Click on one item in the main window to get additional information about it. \endlist @@ -1262,28 +1260,31 @@ Translation files are created as follows: \list 1 - \o Run \l lupdate initially to generate the first set of TS - translation source files with all the user-visible text but no - translations. + \o Run \l {linguist-manager.html#lupdate}{lupdate} initially to + generate the first set of TS translation source files with all the + user-visible text but no translations. \o The TS files are given to the translator who adds translations using \QL. \QL takes care of any changed or deleted source text. - \o Run \l lupdate to incorporate any new text added to the - application. \l lupdate synchronizes the user-visible text from the - application with the translations; it does not destroy any data. + \o Run \l{linguist-manager.html#lupdate}{lupdate} to incorporate any new + text added to the application. \l{linguist-manager.html#lupdate}{lupdate} + synchronizes the user-visible text from the application with the + translations; it does not destroy any data. \o Steps 2 and 3 are repeated as often as necessary. - \o When a release of the application is needed \l lrelease is run to + \o When a release of the application is needed + \l{linguist-manager.html#lrelease}{lrelease} is run to read the TS files and produce the QM files used by the application at runtime. \endlist - For \l lupdate to work successfully, it must know which translation - files to produce. The files are simply listed in the application's \c - .pro Qt project file, for example: + For \l{linguist-manager.html#lupdate}{lupdate} to work successfully, + it must know which translation files to produce. The files are simply + listed in the application's \c .pro Qt project file, for example: \snippet examples/linguist/arrowpad/arrowpad.pro 1 - If your sources contain genuine non-Latin1 strings, \l lupdate needs + If your sources contain genuine non-Latin1 strings, + \l{linguist-manager.html#lupdate}{lupdate} needs to be told about it in the \c .pro file by using, for example, the following line: @@ -1291,7 +1292,8 @@ CODECFORTR = UTF-8 \endcode - See the \l lupdate and \l lrelease sections. + See the \l{linguist-manager.html#lupdate}{lupdate} and + \l{linguist-manager.html#lrelease}{lrelease} sections. \section2 Loading Translations @@ -1354,14 +1356,14 @@ \section2 Distinguishing Between Identical Translatable Strings - The \l lupdate program automatically provides a \e context for every - source text. This context is the class name of the class that contains - the \c tr() call. This is sufficient in the vast majority of cases. - Sometimes however, the translator will need further information to - uniquely identify a source text; for example, a dialog that contained - two separate frames, each of which contained an "Enabled" option would - need each identified because in some languages the translation would - differ between the two. This is easily achieved using the + The \l{linguist-manager.html#lupdate}{lupdate} program automatically + provides a \e context for every source text. This context is the class + name of the class that contains the \c tr() call. This is sufficient in + the vast majority of cases. Sometimes however, the translator will need + further information to uniquely identify a source text; for example, + a dialog that contained two separate frames, each of which contained an + "Enabled" option would need each identified because in some languages the + translation would differ between the two. This is easily achieved using the two argument form of the \c tr() call, e.g. \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 10 @@ -1391,38 +1393,40 @@ \section2 Handling Plural Forms - Qt includes a \c tr() overload that will make it very easy to - write "plural-aware" internationalized applications. This overload + Qt includes a \c tr() overload that will make it very easy to + write "plural-aware" internationalized applications. This overload has the following signature: \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 17 - Depending on the value of \c n, the \c tr() function will return a different - translation, with the correct grammatical number for the target language. + Depending on the value of \c n, the \c tr() function will return a different + translation, with the correct grammatical number for the target language. Also, any occurrence of \c %n is replaced with \c{n}'s value. For example: \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 18 - If a French translation is loaded, this will expand to "0 item - remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items - remplac\unicode{233}s", etc., depending on \c{n}'s value. - And if no translation is loaded, the original string is used, with \c %n + If a French translation is loaded, this will expand to "0 item + remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items + remplac\unicode{233}s", etc., depending on \c{n}'s value. + And if no translation is loaded, the original string is used, with \c %n replaced with count's value (e.g., "6 item(s) replaced"). - To handle plural forms in the native language, you need to load a - translation file for this language, too. \l lupdate has the + To handle plural forms in the native language, you need to load a + translation file for this language, too. + \l{linguist-manager.html#lupdate}{lupdate} has the \c -pluralonly command line option, which allows the creation of TS files containing only entries with plural forms. - See the \l{http://doc.qt.nokia.com/qq/}{Qt Quarterly} Article + See the \l{http://doc.qt.nokia.com/qq/}{Qt Quarterly} Article \l{http://doc.qt.nokia.com/qq/qq19-plurals.html}{Plural Forms in Translations} for further details on this issue. \section2 Coping With C++ Namespaces C++ namespaces and the \c {using namespace} statement can confuse - \l lupdate. It will interpret \c MyClass::tr() as meaning just - that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is + \l{linguist-manager.html#lupdate}{lupdate}. It will interpret + \c MyClass::tr() as meaning just that, not as + \c MyNamespace::MyClass::tr(), even if \c MyClass is defined in the \c MyNamespace namespace. Runtime translation of these strings will fail because of that. @@ -1449,7 +1453,8 @@ If you need to have translatable text completely outside a function, there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). - These macros merely mark the text for extraction by \l{lupdate}. + These macros merely mark the text for extraction by + \l{linguist-manager.html#lupdate}{lupdate}. The macros expand to just the text (without the context). Example of QT_TR_NOOP(): @@ -1484,8 +1489,9 @@ applications for translation. At the beginning of a project add the translation source files to be - used to the project file and add calls to \l lupdate and \l lrelease to - the makefile. + used to the project file and add calls to + \l{linguist-manager.html#lupdate}{lupdate} and + \l{linguist-manager.html#lrelease}{lrelease} to the Makefile. During the project all the programmer must do is wrap any user-visible text in \c tr() calls. They should also use the two argument form for @@ -1508,5 +1514,5 @@ may change in future Qt releases. \quotefile tools/linguist/shared/ts.dtd - + */ diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc index aac6bb0..de6eb7f 100644 --- a/doc/src/platforms/platform-notes.qdoc +++ b/doc/src/platforms/platform-notes.qdoc @@ -735,9 +735,9 @@ \row \o QtCore \o \c AllFiles when \l{http://developer.symbian.org/wiki/index.php/Capabilities_%28Symbian_Signed%29/AllFiles_Capability}{accessing specific areas.} \row \o QtDeclarative - \o \c NetworkServices is automatically added for this module. + \o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified. \row \o QtNetwork - \o \c NetworkServices is automatically added for this module. + \o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified. \row \o QtNetwork \o \c ReadUserData is required to include all the phone's SSL certificates in the system's default CA certificate list (for example those added by the user or stored in the SIM card), @@ -745,7 +745,7 @@ \row \o QtMultiMedia \o \c UserEnvironment if QAudioInput is used. \row \o QtWebkit - \o \c NetworkServices is automatically added for this module. + \o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified. \endtable \note Some modules rely on other modules. E.g. QtWebkit and QtDeclarative diff --git a/doc/src/snippets/code/doc_src_installation.qdoc b/doc/src/snippets/code/doc_src_installation.qdoc index 0374320..1a87566 100644 --- a/doc/src/snippets/code/doc_src_installation.qdoc +++ b/doc/src/snippets/code/doc_src_installation.qdoc @@ -328,9 +328,10 @@ runonphone -s myapp.sis myapp.exe //! [49] //! [50] -nokia_plugin/openc/s60opencsis/openc_ssl_s60_1_6_ss.sis -nokia_plugin/openc/s60opencsis/pips_s60_1_6_ss.sis -nokia_plugin/opencpp/s60opencppsis/stdcpp_s60_1_6_ss.sis +src/s60installs/sqlite3.sis +$EPOCROOT/nokia_plugin/openc/s60opencsis/openc_ssl_s60_1_6_ss.sis +$EPOCROOT/nokia_plugin/openc/s60opencsis/pips_s60_1_6_ss.sis +$EPOCROOT/nokia_plugin/opencpp/s60opencppsis/stdcpp_s60_1_6_ss.sis //! [50] diff --git a/doc/src/sql-programming/sql-driver.qdoc b/doc/src/sql-programming/sql-driver.qdoc index 42cfefd..2cb7aab 100644 --- a/doc/src/sql-programming/sql-driver.qdoc +++ b/doc/src/sql-programming/sql-driver.qdoc @@ -314,7 +314,9 @@ \section3 How to Build the OCI Plugin on Windows Choosing the option "Programmer" in the Oracle Client Installer from - the Oracle Client Installation CD is sufficient to build the plugin. + the Oracle Client Installation CD is generally sufficient to build the + plugin. For some versions of Oracle Client, you may also need to select + the "Call Interface (OCI)" option if it is available. Build the plugin as follows (here it is assumed that Oracle Client is installed in \c{C:\oracle}): |