Merge branch 'kinetic-declarativeui' of git://git-nokia.trolltech.com.au/qtsoftware/qt/kinetic

Conflicts:
	src/xmlpatterns/type/qprimitives_p.h
	tools/linguist/lupdate/main.cpp

1 files changed, 179 insertions, 0 deletions

diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
new file mode 100644
index 0000000..fede2cd
--- /dev/null
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -0,0 +1,179 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qmldynamicobjects.html
+\title Dynamic Object Creation
+
+QML has some support for dynamically loading and managing QML objects from
+within Javascript blocks. It is preferable to use the existing QML elements for
+dynamic object management wherever possible; these are \l{Loader}, 
+\l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView}. It is also possible 
+to dynamically create and manage objects from C++, and this is preferable for 
+hybrid QML/C++ applications - see \l{Using QML in C++ Applications}.
+Dynamically creating and managing objects from 
+within Javascript blocks is intended for when none of the existing QML elements 
+fit the needs of your application, and you do not desire for your application 
+to involve C++ code.
+
+\section1 Creating Objects Dynamically
+There are two ways of creating objects dynamically. You can either create
+a component which instantiates items, or create an item from a string of QML.
+Creating a component is better for the situation where you have a predefined
+item which you want to manage dynamic instances of, and creating an item from
+a string of QML is intended for when the QML itself is generated at runtime.
+
+If you have a component specified in a QML file, you can dynamically load it with
+the createComponent function on the \l{QML Global Object}. 
+This function takes the URL of the QML file as its only argument and returns
+a component object which can be used to create and load that QML file.
+
+You can also create a component by placing your QML inside a Component element.
+Referencing that component element by id will be the same as referencing the variable
+which you save the result of createComponent into.
+
+Once you have a component you can use its createObject method to create an instance of
+the component. Example QML script is below. Remember that QML files that might be loaded
+    over the network cannot be expected to be ready immediately.
+    \code
+        var component;
+        var sprite;
+        function finishCreation(){
+            if(component.isReady()){
+                sprite = component.createObject();
+                if(sprite == 0){
+                    // Error Handling
+                }else{
+                    sprite.parent = page;
+                    sprite.x = 200;
+                    //...
+                }
+            }else if(component.isError()){
+                // Error Handling
+            }
+        }
+
+        component = createComponent("Sprite.qml");
+        if(component.isReady()){
+            finishCreation();
+        }else{
+            component.statusChanged.connect(finishCreation);
+        }
+    \endcode
+
+    If you are certain the files will be local, you could simplify to
+
+    \code
+        component = createComponent("Sprite.qml");
+        sprite = component.createObject();
+        if(sprite == 0){
+            // Error Handling
+            console.log(component.errorsString());
+        }else{
+            sprite.parent = page;
+            sprite.x = 200;
+            //...
+        }
+    \endcode
+
+After creating the item, remember to set its parent to an item within the scene.
+Otherwise your dynamically created item will not appear in the scene. When using files with relative paths, the path should
+be relative to the file where createComponent is executed.
+
+If the QML does not exist until runtime, you can create a QML item from
+a string of QML using the createQmlObject function, as in the following example:
+
+    \code
+    newObject = createQmlObject('import Qt 4.6; Rectangle {color: "red"; width: 20; height: 20}',
+        targetItem, "dynamicSnippet1");
+    \endcode
+The first argument is the string of QML to create. Just like in a new file, you will need to
+import any types you wish to use. For importing files with relative paths, the path should
+be relative to the file where the item in the second argument is defined. Remember to set the parent after
+creating the item. The second argument is another item in the scene, and the new item is created
+in the same QML Context as this item. The third argument is the file path associated with this
+item, which is used for error reporting.
+
+\section1 Maintaining Dynamically Created Objects
+
+Dynamically created objects may be used the same as other objects, however they
+will not have an id in QML.
+
+A restriction which you need to manage with dynamically created items,
+is that the creation context must outlive the
+created item. The creation context is the QmlContext in which createComponent
+was called, or the context in which the Component element, or the item used as the
+second argument to createQmlObject, was specified. If the creation
+context is destroyed before the dynamic item is, then bindings in the dynamic item will
+fail to work.
+
+\section1 Deleting Objects Dynamically
+You should generally avoid dynamically deleting objects that you did not
+dynamically create. In many UIs, it is sufficient to set the opacity to 0 or
+to move the item off of the edge of the screen. If you have lots of dynamically
+created items however, deleting them when they are no longer used will provide
+a worthwhile performance benefit. Note that you should never manually delete
+items which were dynamically created by QML Elements such as \l{Loader}.
+
+To manually delete a QML item, call its destroy method. This method has one
+argument, which is an approximate delay in ms and which defaults to zero. This
+allows you to wait until the completion of an animation or transition. An example:
+
+\code
+    Component{ id:fadesOut
+        Rectangle{
+            id: rect
+            width: 40; height: 40;
+            opacity: NumberAnimation{from:1; to:0; duration: 1000;}
+            Component.onCompleted: rect.destroy(1000);
+        }
+    }
+    function createFadesOut(parentItem)
+    {
+        var object = fadesOut.createObject();
+        object.parent = parentItem;
+    }
+\endcode
+In the above example, the dynamically created rectangle calls destroy as soon as it's created,
+ but delays long enough for its fade out animation to play.
+
+*/
+