Merge branch '4.8' of scm.dev.nokia.troll.no:qt/qt into 4.8

2 files changed, 172 insertions, 0 deletions

diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index dbc8806..f2e24f2 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -310,6 +310,7 @@ It is defined by a plain text file named "qmldir" that contains one or more line
 <TypeName> [<InitialVersion>] <File>
 internal <TypeName> <File>
 plugin <Name> [<Path>]
+typeinfo <File>
 \endcode
 
 \bold {# <Comment>} lines are used for comments. They are ignored by the QML engine.
@@ -350,6 +351,14 @@ plugin file, or a relative path from the directory containing the \c qmldir file
 containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir
 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.
 
+\bold {typeinfo <File>} lines add \l{Writing a qmltypes file}{type description files} to
+the module that can be read by QML tools such as Qt Creator to get information about the
+types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes
+file.
+
+Without such a file QML tools may be unable to offer features such as code completion
+for the types defined in your plugins.
+
 
 \section1 Debugging
 
@@ -358,5 +367,119 @@ when there are problems with finding and loading modules. See
 \l{Debugging module imports} for more information.
 
 
+\section1 Writing a qmltypes file
+
+QML modules may refer to one or more type information files in their
+\l{Writing a qmldir file}{qmldir} file. These usually have the .qmltypes
+extension and are read by external tools to gain information about
+types defined in plugins.
+
+As such qmltypes files have no effect on the functionality of a QML module.
+Their only use is to allow tools such as Qt Creator to provide code completion,
+error checking and other functionality to users of your module.
+
+Any module that uses plugins should also ship a type description file.
+
+The best way to create a qmltypes file for your module is to generate it
+using the \c qmlplugindump tool that is provided with Qt.
+
+Example:
+If your module is in \c /tmp/imports/My/Module, you could run
+\code
+qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes
+\endcode
+to generate type information for your module. Afterwards, add the line
+\code
+typeinfo mymodule.qmltypes
+\endcode
+to \c /tmp/imports/My/Module/qmldir to register it.
+
+While the qmldump tool covers most cases, it does not work if:
+\list
+\o The plugin uses a \l{QDeclarativeCustomParser}. The component that uses
+   the custom parser will not get its members documented.
+\o The plugin can not be loaded. In particular if you cross-compiled
+   the plugin for a different architecture, qmldump will not be able to
+   load it.
+\endlist
+
+In case you have to create a qmltypes file manually or need to adjust
+an existing one, this is the file format:
+
+\qml
+import QtQuick.tooling 1.0
+
+// There always is a single Module object that contains all
+// Component objects.
+Module {
+    // A Component object directly corresponds to a type exported
+    // in a plugin with a call to qmlRegisterType.
+    Component {
+
+        // The name is a unique identifier used to refer to this type.
+        // It is recommended you simply use the C++ type name.
+        name: "QDeclarativeAbstractAnimation"
+
+        // The name of the prototype Component.
+        prototype: "QObject"
+
+        // The name of the default property.
+        defaultProperty: "animations"
+
+        // The name of the type containing attached properties
+        // and methods.
+        attachedType: "QDeclarativeAnimationAttached"
+
+        // The list of exports determines how a type can be imported.
+        // Each string has the format "URI/Name version" and matches the
+        // arguments to qmlRegisterType. Usually types are only exported
+        // once, if at all.
+        // If the "URI/" part of the string is missing that means the
+        // type should be put into the package defined by the URI the
+        // module was imported with.
+        // For example if this module was imported with 'import Foo 4.8'
+        // the Animation object would be found in the package Foo and
+        // QtQuick.
+        exports: [
+            "Animation 4.7",
+            "QtQuick/Animation 1.0"
+        ]
+
+        Property {
+            name: "animations";
+            type: "QDeclarativeAbstractAnimation"
+            // defaults to false, whether this property is read only
+            isReadonly: true
+            // defaults to false, whether the type of this property was a pointer in C++
+            isPointer: true
+            // defaults to false: whether the type actually is a QDeclarativeListProperty<type>
+            isList: true
+        }
+        Property { name: "loops"; type: "int" }
+        Property { name: "name"; type: "string" }
+        Property { name: "loopsEnum"; type: "Loops" }
+
+        Enum {
+            name: "Loops"
+            values: {
+                "Infinite": -2,
+                "OnceOnly": 1
+            }
+        }
+
+        // Signal and Method work the same way. The inner Parameter
+        // declarations also support the isReadonly, isPointer and isList
+        // attributes which mean the same as for Property
+        Method { name: "restart" }
+        Signal { name: "started" }
+        Signal {
+            name: "runningChanged"
+            Parameter { type: "bool" }
+            Parameter { name: "foo"; type: "bool" }
+        }
+    }
+}
+\endqml
+
 */
 /
diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc
index 494d129..55d5c55 100644
--- a/doc/src/development/qmake-manual.qdoc
+++ b/doc/src/development/qmake-manual.qdoc
@@ -1120,6 +1120,44 @@
 
     \tableofcontents{3}
 
+
+    \target BACKUP_REGISTRATION_FILE_MAEMO
+    \section1 BACKUP_REGISTRATION_FILE_MAEMO
+
+    \e {This is only used on the Maemo platform.}
+
+    This variable is used to specify the backup registration file to use with
+    \c enable_backup \c CONFIG value for Maemo platform. The default value is:
+    \c{$$_PRO_FILE_PWD_/backup_registration/maemo/$$basename(TARGET).conf}.
+
+    Unfortunately it is not possible to have a common registration file for Maemo like there is
+    for Symbian, so the developer must always provide one if the platform default backup support is
+    not sufficient.
+
+    For documentation about how to create backup registration files and how the device
+    backup works in general, see:
+    (\l{http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Generic_Platform_Components/Using_Backup_Application}{Using Backup Application})
+
+    \target BACKUP_REGISTRATION_FILE_SYMBIAN
+    \section1 BACKUP_REGISTRATION_FILE_SYMBIAN
+
+    \e {This is only used on the Symbian platform.}
+
+    This variable is used to specify the backup registration file to use with
+    \c enable_backup \c CONFIG value for Symbian platform. The default value is
+    determined as follows:
+
+    If a custom registration file \c{$$_PRO_FILE_PWD_/backup_registration/symbian/backup_registration.xml}
+    exists, it is used. Otherwise, the common registration file \c{$$[QT_INSTALL_DATA]/mkspecs/common/symbian/backup_registration.xml}
+    is used. This common registration file will define backing up of application binaries,
+    resources, and all files under application private directory. Also note that \c{C:/Data}
+    contents are backed up by default on Symbian devices, so no registration is needed for any
+    files found there.
+
+    For documentation about how to create backup registration files and how the device
+    backup works in general, see:
+    (\l{http://library.forum.nokia.com/index.jsp?topic=/S60_5th_Edition_Cpp_Developers_Library/GUID-35228542-8C95-4849-A73F-2B4F082F0C44/sdk/doc_source/guide/Connectivity-subsystem-guide/Connectivity/PC_Connectivity_How-To_Write_Backup_Aware_Software.html}{How-To Write Backup-aware Software})
+
     \target BLD_INF_RULES
     \section1 BLD_INF_RULES
 
@@ -1342,6 +1380,17 @@
          so some \c{.ts} files may be ignored by qmake.
     \endtable
 
+    These options only have an effect on Symbian and Maemo platforms:
+
+    \table 95%
+    \header \o Option \o Description
+    \row \o enable_backup \o Generates deployment for backup registration file
+         to enable backing up the application during device backup.
+         See \l{#BACKUP_REGISTRATION_FILE_MAEMO}{BACKUP_REGISTRATION_FILE_MAEMO}
+         and \l{#BACKUP_REGISTRATION_FILE_SYMBIAN}{BACKUP_REGISTRATION_FILE_SYMBIAN}
+         for more information about backup.
+    \endtable
+
     These options have an effect on Linux/Unix platforms:
 
     \table 95%