Merge branch 'kinetic-declarativeui' of scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui

9 files changed, 203 insertions, 714 deletions

diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc
index 3ea5989..0eda95e 100644
--- a/doc/src/declarative/elements.qdoc
+++ b/doc/src/declarative/elements.qdoc
@@ -88,7 +88,6 @@ The following table lists the QML elements provided by the Qt Declarative module
 \o \l ListModel, \l ListElement
 \o \l VisualItemModel
 \o \l XmlListModel and XmlRole
-\o \l SqlQuery, \l SqlConnection, and \l SqlBind
 \o \l DateTimeFormatter
 \o \l NumberFormatter
 \endlist
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc
index afbe3db..e327047 100644
--- a/doc/src/declarative/globalobject.qdoc
+++ b/doc/src/declarative/globalobject.qdoc
@@ -42,7 +42,6 @@
 /*!
 \page qmlglobalobject.html
 \title QML Global Object
-
 Contains all the properties of the ECMAScript global object, plus:
 
 \list
@@ -53,37 +52,186 @@ Contains all the properties of the ECMAScript global object, plus:
 \o openDatabase
 \endlist
 
+Contents:
+\tableofcontents
 
 \section1 Qt Object
 
-The Qt object contains functions for
+The Qt object provides useful enums and functions from Qt, for use in all QML
+files. 
 
-creating types:
-\list
-\o hsla
-\o rgba
-\o rect
-\o point
-\o size
-\o vector3d
-\endlist
+\section2 Enums
+The Qt object contains all enums in the Qt namespace. For example, you can
+access the AlignLeft member of the Qt::AlignmentFlag enum with \c Qt.AlignLeft.
+
+For a full list of enums, see the Qt Namespace documentation.
+
+\section2 Types
+The Qt object also contains helper functions for creating objects of specific
+data types. This is primarily useful when setting the properties of an item
+when the property has one of the following types:
 
-manipulating color:
 \list
-\o lighter
-\o darker
-\o tint
+\o Color
+\o Rect
+\o Point
+\o Size
+\o Vector3D
 \endlist
 
-and playing sound:
-\list
-\o playSound
+There are also string based constructors for these types, see \l{basicqmltypes.html}{Qml Types}.
+
+\section3 Qt.rgba(int red, int green, int blue, int alpha)
+This function returns a Color with the specified \c red, \c green, \c blue and \c alpha components. All components should be in the range 0-1 inclusive.
+
+\section3 Qt.hsla(int hue, int saturation, int lightness, int alpha)
+This function returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components. All components should be in the range 0-1 inclusive.
+
+\section3 Qt.rect(int x, int y, int width, int height) 
+This function returns a Rect with the top-left corner at \c x,\c y and the specified \c width and \c height.
+\section3 Qt.point(int x, int y)
+This function returns a Point with the specified \c x and \c y coordinates.
+\section3 Qt.size(int width, int height)
+returns as Size with the specified width and height.
+\section3 Qt.vector(real x, real y, real z)
+    This function is intended for use inside QML only. In C++ just create a
+    QVector3D as usual.
+
+    This function takes three numeric components and combines them into a
+    QVector3D value that can be used with any property that takes a
+    QVector3D argument.  The following QML code:
+
+    \code
+    transform: Rotation {
+        id: rotation
+        origin.x: Container.width / 2;
+        axis: vector(0, 1, 1)
+    }
+    \endcode
+
+    is equivalent to:
+
+    \code
+    transform: Rotation {
+        id: rotation
+        origin.x: Container.width / 2;
+        axis.x: 0; axis.y: 1; axis.z: 0
+    }
+    \endcode
+
+
+\section2 Functions
+The Qt object also contains the following miscellaneous functions which expose Qt functionality for use in QML.
+
+\section3 Qt.lighter(color baseColor)
+This function returns a color 50% lighter than \c baseColor. See QColor::lighter() for further details.
+\section3 Qt.darker(color baseColor)
+This function returns a color 50% darker than \c baseColor. See QColor::lighter() for further details.
+\section3 Qt.tint(color baseColor, color tintColor)
+    This function allows tinting one color with another.
+
+    The tint color should usually be mostly transparent, or you will not be able to see the underlying color. The below example provides a slight red tint by having the tint color be pure red which is only 1/16th opaque.
+
+    \qml
+    Rectangle { x: 0; width: 80; height: 80; color: "lightsteelblue" }
+    Rectangle { x: 100; width: 80; height: 80; color: Qt.tint("lightsteelblue", "#10FF0000") }
+    \endqml
+    \image declarative-rect_tint.png
+
+    Tint is most useful when a subtle change is intended to be conveyed due to some event; you can then use tinting to more effectively tune the visible color.
+\section3 Qt.playSound(url soundLocation)
+This function plays the audio file located at \c soundLocation. Only .wav files are supported.
+
+\section3 Qt.openUrlExternally(url target)
+This function attempts to open the specified \c target url in an external application, based on the user's desktop preferences. It will return true if it succeeds, and false otherwise.
 \endlist
 
-It also contains enum values used by some items.
+\section1 Dynamic Object Creation
+The following functions on the global object allow you to dynamically create QML
+items from files or strings. 
 
-\section1 Asynchronous JavaScript and XML 
+You can also dynamically create objects in a declarative manner, using items
+such as ListView, Repeater and Loader. 
+
+\section2 createComponent(url file)
+    This function takes the URL of a QML file as its only argument. It returns
+    a component object which can be used to create and load that QML file.
+
+    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
+            print(component.errorsString());
+        }else{
+            sprite.parent = page;
+            sprite.x = 200;
+            //...
+        }
+    \endcode
+
+    If you want to just create an arbitrary string of QML, instead of
+    loading a QML file, consider the createQmlObject() function.
+
+\section2 createQmlObject(string qml, object parent, string filepath)
+    Creates a new object from the specified string of QML. It requires a
+    second argument, which is the id of an existing QML object to use as
+    the new object's parent. If a third argument is provided, this is used
+    for error reporting as the filepath that the QML came from.
+
+    Example (where targetItem is the id of an existing QML item):
+    \code
+    newObject = createQmlObject('import Qt 4.6; Rectangle {color: "red"; width: 20; height: 20}',
+        targetItem, "dynamicSnippet1");
+    \endcode
+
+    This function is intended for use inside QML only. It is intended to behave
+    similarly to eval, but for creating QML elements.
+
+    Returns the created object, or null if there is an error. In the case of an
+    error, details of the error are output using qWarning().
+
+    Note that this function returns immediately, and therefore may not work if
+    the QML loads new components. If you are trying to load a new component,
+    for example from a QML file, consider the createComponent() function
+    instead. 'New components' refers to external QML files that have not yet
+    been loaded, and so it is safe to use createQmlObject to load built-in
+    components.
+
+\section1 Asynchronous JavaScript and XML 
+QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain data from over a network.
+\section2 XMLHttpRequest()
+In QML you can construct an XMLHttpRequest object just like in a web browser! TODO: Real documentation for this object.
 \section1 Offline Storage API
 
 The \c openDatabase() and related functions
diff --git a/doc/src/declarative/measuring-performance.qdoc b/doc/src/declarative/measuring-performance.qdoc
index 01e7b03..bd1b0eb 100644
--- a/doc/src/declarative/measuring-performance.qdoc
+++ b/doc/src/declarative/measuring-performance.qdoc
@@ -71,14 +71,14 @@ Q_DEFINE_PERFORMANCE_METRIC(TextSize, "Text Size Calculation");
 You could then use this category in the code:
 
 \code
-void QFxText::updateSize()
+void QmlGraphicsText::updateSize()
 {
-    QFxPerfTimer<QFxPerf::TextSize> perf;
+    QmlPerfTimer<QmlPerf::TextSize> perf;
     ...
 }
 \endcode
 
-Because there is no cost for a QFxPerfTimer when Q_ENABLE_PERFORMANCE_LOG is not defined, this line can persist in the code and be used to help detect performance bottlenecks and regressions. See the QPerformanceLog documentation for more information on this performance framework.
+Because there is no cost for a QmlPerfTimer when Q_ENABLE_PERFORMANCE_LOG is not defined, this line can persist in the code and be used to help detect performance bottlenecks and regressions. See the QPerformanceLog documentation for more information on this performance framework.
 
 \section1 FPS Measurements
 
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index 5d8623b..ea8e198 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -98,12 +98,7 @@ completely new applications.  QML is fully \l {Extending QML}{extensible from C+
 \section1 Reference:
 \list
 \o \l {QML Elements}
+\o \l {QML Global Object}
 \o \l {Extending QML}
 \endlist
-
-\section1 Deprecated
-\list
-\o \l {tutorials-declarative-contacts.html}{Tutorial: 'Introduction to QML'}
-\endlist
-
 */
diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc
index 4c28255..6892005 100644
--- a/doc/src/declarative/qtprogrammers.qdoc
+++ b/doc/src/declarative/qtprogrammers.qdoc
@@ -84,14 +84,14 @@ QML Items also serve these purposes. Each is considered separately below.
 
 \section2 Simple Widgets
 
-The most important rule to remember while implementing a new QFxItem in C++
+The most important rule to remember while implementing a new QmlGraphicsItem in C++
 is that it should not contain any look and feel policies - leave that to the
 QML usage of the item.
 
 As an example, imagine you wanted a reusable Button item. If you therefore
-decided to write a QFxItem subclass to implement a button,
+decided to write a QmlGraphicsItem subclass to implement a button,
 just as QToolButton subclasses QWidget for this purpose, following the rule above, your
-\c QFxButton would not have any appearance - just the notions of enabled, triggering, etc.
+\c QmlGraphicsButton would not have any appearance - just the notions of enabled, triggering, etc.
 
 But there is already an object in Qt that does this: QAction.
 
@@ -103,8 +103,8 @@ The look and feel of an action - the appearance of the button, the transition be
 and exactly how it respond to mouse, key, or touch input, should all be left for definition
 in QML.
 
-It is illustrative to note that QFxTextEdit is built upon QTextControl,
-QFxWebView is built upon QWebPage, and ListView uses QListModelInterface,
+It is illustrative to note that QmlGraphicsTextEdit is built upon QTextControl,
+QmlGraphicsWebView is built upon QWebPage, and ListView uses QListModelInterface,
 just as QTextEdit, QWebView, and QListView are built upon
 those same UI-agnostic components.
 
diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc
index d040d3d..6c53242 100644
--- a/doc/src/development/qmake-manual.qdoc
+++ b/doc/src/development/qmake-manual.qdoc
@@ -2341,6 +2341,11 @@ For example:
     of this variable is typically handled by \c qmake or
      \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
 
+    \section1 QMAKE_LFLAGS_RPATH
+    
+    Library paths in this definition are added to the executable at link
+    time so that the added paths will be preferentially searched at runtime.
+    
     \section1 QMAKE_LFLAGS_QT_DLL
 
     This variable contains link flags when building programs that
@@ -2667,6 +2672,16 @@ For example:
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 45
 
+    \section1 QMAKE_RPATH
+
+    Is equivalent to \l QMAKE_LFLAGS_RPATH.
+
+    \section1 QMAKE_RPATHDIR
+
+    A list of library directory paths, these paths are added to the
+    executable at link time so that the paths will be preferentially
+    searched at runtime.
+
     \section1 QMAKE_RUN_CC
 
     This variable specifies the individual rule needed to build an object.
diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc
index 8269552..e127429 100644
--- a/doc/src/getting-started/installation.qdoc
+++ b/doc/src/getting-started/installation.qdoc
@@ -963,16 +963,23 @@ Symbian platform, see \l{Symbian platform - Introduction to using Qt}.
 
     Qt for Symbian platform requires the following software installed on your development PC:
     \list
-        \o \l{http://www.mingw.org/}{MinGW 3.4.5 or higher}, or another windows compiler to build the tools.
         \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://downloads.activestate.com/ActivePerl/Windows/5.6/ActivePerl-5.6.1.638-MSWin32-x86.msi}{ActivePerl v5.6.1 build 638}
+           \list
+           \o \bold{Note:} According to Symbian, version 5.6.1 build 638 is mandatory. Using later versions may result in unexplained errors.
+           \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 Symbian SDKs you plan to use Qt with.
+        \o Building Qt tools from scratch requires \l{http://www.mingw.org/}{MinGW 3.4.5 or higher}, or another windows compiler.
+           \list
+           \o \bold{Note:} This is not required if you are using pre-built binary package.
+           \endlist
         \o Building Qt libraries requires \l{http://www.arm.com/products/DevTools/RVCT.html}{RVCT} 2.2 [build 686] or later,
            which is not available free of charge. 
     \endlist
diff --git a/doc/src/platforms/qt-embedded.qdoc b/doc/src/platforms/qt-embedded.qdoc
index c39a967..e0c35cc 100644
--- a/doc/src/platforms/qt-embedded.qdoc
+++ b/doc/src/platforms/qt-embedded.qdoc
@@ -68,10 +68,9 @@
     environment and use native features, such as menus, to conform
     to the native style guidelines.
     \o \l{Symbian platform - Introduction to using Qt}{Qt for the Symbian
-platform} is used to create
-    applications running in existing Symbian platform environments.
-    Applications use the appropriate style for the embedded
-    environment and use native features, such as menus, to conform
+    platform} is used to create applications running in existing Symbian
+    platform environments. Applications use the appropriate style for the
+    embedded environment and use native features, such as menus, to conform
     to the native style guidelines.
     \endtable
 */
diff --git a/doc/src/tutorials/declarative.qdoc b/doc/src/tutorials/declarative.qdoc
deleted file mode 100644
index bbc3d15..0000000
--- a/doc/src/tutorials/declarative.qdoc
+++ /dev/null
@@ -1,674 +0,0 @@
-/****************************************************************************
-**
-** 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 tutorials-declarative-contacts.html
-    \startpage {index.html}{Qt Reference Documentation}
-    \nextpage {tutorials/declarative/contacts/part1}{Chapter 1}
-
-    \title Declarative UI Tutorial
-    \ingroup howto
-    \ingroup tutorials
-    \brief An introduction to using Qt Declarative UI to put together a
-    simple animated application.
-
-    \omit
-    At the time of writing the tutorial Declarative UI was still under
-    development.  It is extremely likely that an update will be required
-    prior to 4.6 release.
-    \endomit
-
-    This tutorial gives an introduction to using the Qt Declarative UI
-    animation framework.
-
-    In this process we will learn about some of the basics of using
-    Declarative UI, such as
-
-    \list
-    \o Basic drawing
-    \o States and Transitions
-    \o Reuse of components
-    \o Models and Views
-    \endlist
-
-    An existing knowledge of Qt is not required.
-
-    The tutorial's source code is located in Qt's
-    \c examples/declarative/tutorials/contacts directory.
-    It is split up into a number of sub directories, and within each
-    sub directory the files are numbered in an order of increasing features.
-
-    The code in this example is not compiled, but interpreted at run time.
-    This means you should use the qmlviewer application provided with
-    Qt to run the examples.
-
-    \list
-    \o \l{tutorials/declarative/contacts/part1}{Drawing and Animation}
-    \o \l{tutorials/declarative/contacts/part2}{Reusing QML Components}
-    \o \l{tutorials/declarative/contacts/part3}{Models, Views and Delegates}
-    \endlist
-*/
-
-/*!
-    \page tutorials-declarative-contacts-part1.html
-    \contentspage {Declarative UI Tutorial}{Contents}
-    \nextpage {tutorials/declarative/contacts/part2}{Chapter 2}
-    \example tutorials/declarative/contacts/part1
-    \title Drawing and Animation
-    \tableofcontents
-
-    The first part of this tutorial covers basic drawing of elements on the
-    screen and causing them to animate.
-
-    \section1 Drawing
-
-    In this first chapter we will build a button that indicates something
-    can be removed and asks for confirmation.  When clicked it will expand
-    from a small button with a trash can icon, to a wide button with a
-    confirm icon on the left, the text "Remove" in the middle, and a
-    cancel icon on the right.
-
-    \image declarative-removebutton.gif
-
-    Because Declarative UI is declarative, you don't pass instructions on
-    what to paint in a sequential manner as you may be used to.  Instead
-    elements and how they appear on the screen are declared in much the
-    same was as elements on a web page are declared.  This is done using
-    the Qt Markup Language which we will refer to by the abbreviation QML
-    for the remainder of the tutorial.
-
-    We will start by drawing a simple red rectangle with rounded corners.
-
-    \image declarative-roundrect.png
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/1/RemoveButton.qml 0
-
-    This is one of the simplest of QML components.  It describes a rectangle with
-    some simple properties.  In QML all components start with a capital
-    letter, and their properties with lower case letters.
-
-    Apart from the properties all QML components share, the \l{Rectangle}{Rectangle} component has the properties
-
-    \list
-    \o color - The background color of the rectangle
-    \o tintColor - The overlay color of the rectangle
-    \o gradientColor - The color at the base of the rectangle to blend upwards
-    \o pen - The description of how to draw the border of the rectangle
-    \o radius - The corner radius used to draw rounded rectangles.
-    \endlist
-
-    There are also a number of properties all QML components shares, described
-    in the \l{Item}{Item} element reference documentation.  The rectangle drawn in the
-    above code uses the properties;
-
-    \list
-    \o id - An identifier of the component
-    \o width - the width of the component when drawn
-    \o height - the height of the component when drawn
-    \endlist
-
-    Currently we have described a rectangle with a width and height of 30 pixels, filled in with
-    the color red and with rounded corners using a radius of 5.
-
-    \section1 Layout
-
-    The next step of the tutorial adds an image over the rectangle.  We
-    will do this by adding an \l{Image}{Image} component as a child of the
-    \l{Rectangle}{Rectangle} component.  All QML components have a list of children which
-    are drawn in order after the parent component has been drawn.
-    By having the \l{Image}{Image}
-    component as a child of the \l{Rectangle}{Rectangle} component we ensure it is drawn
-    over the \l{Rectangle}{Rectangle} component.  Children also are affected by the opacity
-    of the parent component and calculate their position in within the bounds of
-    the parent component.
-
-    \image declarative-removebutton-close.png
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/2/RemoveButton.qml 0
-
-    The trashIcon image is added as a child of the Rectangle.  In this case
-    the children property isn't explicitly used because the default property
-    of the \l{Rectangle}{Rectangle} component is its children.  Some elements often don't have children
-    and use some other default component.  When this is the case its possible
-    to explicitly list the sub component as a child as follows:
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/2a/RemoveButton.qml 0
-
-    The \l{Image}{Image} element allows loading an image file for display.  The source
-    specified is a URL, and in this case refers to a portable network graphics
-    file in a relative directory to where the QML file was loaded from.
-
-    Also new in this code is the use of anchors.  In QML components can either
-    have their position and size specified explicitly using x, y, width
-    and height, or they can instead specify the size and position in relation
-    to either parent or sibling elements.  The \l{Image}{Image} component uses
-    a combination of both styles.  It has a fixed size, but specifies its
-    position to align to the right of its parent and for its vertical center
-    to align with the vertical center of its parent.  Setting a property
-    by the identifier of a separate property binds them.  This means
-    that if while running the example the position of the \l{Rectangle}{Rectangle} component's
-    vertical center changed, so to would the vertical center of
-    the \l{Image}{Image} component.
-
-    The parent value is a special identifier that always refers to the
-    parent component of a component.
-
-    Anchors are most useful when the size of items might change based on
-    the component state or contents.  However they are limited in that they
-    must always refer to a parent or sibling component.  See
-    \l{anchor-layout}{Anchor-based Layout} for more information on using
-    anchors in QML.
-
-    At this point the initial state of the RemoveButton is complete.  A small
-    rounded rectangle with a trash icon.  Next we will design the open
-    state for the button.
-
-    \image declarative-removebutton-open.png
-
-    This is a wider rectangle with two images and some text.  The code to
-    draw this state of the button could be written as follows:
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/3/RemoveButton.qml 0
-
-    The rectangle width is now wider by 200 pixels.  Also the trashIcon has
-    been replaced.  Normally we wouldn't
-    remove the trashIcon when developing an alternate state of the RemoveButton,
-    however since this is a tutorial its been done so that its easier to
-    understand the alternate state we are aiming for and how it relates to
-    transitioning between states.
-
-    We also introduce the \l{Text}{Text} element.
-    Left and Right anchors are specified in terms of the neighboring icons
-    because we want text to fill the space between the icons.  This
-    means as the parent removeButton gets wider, so will the text component.
-    It also means that if we animate a width change on the removeButton,
-    any bindings, that is the values specified by an expression such as
-    \c{parent.left} will be evaluated and animated as well.
-
-    \section1 Defining States
-
-    When designing a component with multiple states, it should be developed
-    in the initial state and the changes that would be made specified
-    as an additional state.  Its not normally possible to add new children
-    to an element when changing state
-    This means that all possible child components should be included
-    in the initial state, and those that should not be visible in the initial
-    state should have their opacity set to zero.  Thus
-    for the RemoveButton we specify the starting size of the RemoveButton
-    and hide any items that should not initially be visible.
-
-    The code snippet below shows what the start of the duel state specification
-    might look like.
-
-    \code
-    Rectangle {
-        id: removeButton
-        width: 30
-        height: 30
-        color: "red"
-        radius: 5
-        Image {
-            id: trashIcon
-            width: 22
-            height: 22
-            anchors.right: parent.right
-            anchors.rightMargin: 4
-            anchors.verticalCenter: parent.verticalCenter
-            src: "../../shared/pics/trash.png"
-            opacity: 1
-        }
-        Image {
-            id: cancelIcon
-            width: 22
-            height: 22
-            anchors.right: parent.right
-            anchors.rightMargin: 4
-            anchors.verticalCenter: parent.verticalCenter
-            src: "../../shared/pics/cancel.png"
-            opacity: 0
-        }
-    \endcode
-
-    The code above includes components from both states of the RemoveButton,
-    but by setting opacity="0" for the cancelIcon it means that the
-    components of the second state won't be drawn yet.
-    The base state of a component always has an empty name, however new
-    states can be added that describe how a component and its children
-    should be changed.  For the RemoveButton there is only one non-base state
-    required.  In this tutorial we will name it the 'opened' state.
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/4/RemoveButton.qml states
-
-    In the opened state the width of the button itself changes from the base
-    width of 30 to the new width of 230.  Also the opacity of the children
-    are changed so that the trash icon is now hidden and the other elements
-    are now visible.
-
-    \section1 Changing States
-
-    To trigger the change we will react to the 'clicked' signal of a
-    MouseRegion component.
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/4/RemoveButton.qml mouse region
-
-    MouseRegion components handle mouse actions within their geometry.  This
-    geometry behaves the same way as painted components, such that children
-    cover their parents and later siblings will cover earlier siblings and
-    all the children of the earlier sibling, should they overlap.
-
-    When a component has a signal, such as clicked, the action for the signal
-    can be specified using \c{onSignalName}, as is done above.  In this
-    case when the clicked signal is emitted by the MouseRegion component,
-    a function called \c{toggle()} is called.  It might also have been written
-
-    \code
-    onClicked: { removeButton.state='opened' }
-    \endcode
-
-    However in this case we are using a function because it allows multiple
-    mouse regions to use the same functionality, and also makes it
-    easier to specify complex behavior in response to a signal.
-
-    An alternative would be to explicitly state the connection:
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/4a/RemoveButton.qml mouse region
-
-    This will connect to the \c{clicked()} signal of the trashMouseRegion component
-    and execute the associated script.
-
-    The \c{toggle()} function is a new function specified as part of the remove
-    button element.
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/4/RemoveButton.qml script
-
-    Any QML component can have a set of resources specified.  One of those
-    resources is any Script that might be needed.   See the
-    \l{QtScript Module} for more information on how to write
-    script code in Qt.
-
-    It is possible to refer to identified QML components
-    within the script.  Hence the function for our RemoveButton will check
-    if the state is already open to determine what the new state should be.
-
-    \section1 Animation
-
-    Currently the RemoveButton is functional, but snaps between our two states.
-    Fortunately making the transition between states smooth is very simple.
-    We only need one more bit of code at the end of our removeButton component.
-
-    \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/5/RemoveButton.qml transition
-
-    All QML components have a transitions property.  This describes how
-    properties of items within the component should change.  In this case
-    we specify that if the x, width or opacity of the removeButton or its
-    children change due to a change in state, that they should take 200ms
-    to complete their transition.
-
-    \omit
-        TODO More on types of animation, e.g. ColorAnimation, Behaviors.
-    \endomit
-
-    In the next chapter we will show how we can use the remove button in
-    other QML components.
-*/
-
-/*!
-    \page tutorials-declarative-contacts-part2.html
-    \contentspage {Declarative UI Tutorial}{Contents}
-    \previouspage {tutorials/declarative/contacts/part1}{Chapter 1}
-    \nextpage {tutorials/declarative/contacts/part3}{Chapter 3}
-    \example tutorials/declarative/contacts/part2
-    \title Reusing QML Components
-    \tableofcontents
-
-    The second part of this tutorial covers how to reuse QML components and
-    have them interact with each other.  The RemoveButton developed in the
-    previous chapter is intended to be part of a more complex control for
-    editing a field of our contact.  This ContactField in turn is intended
-    to be used in a contact editing control.
-
-    \image declarative-reuse-3.png
-
-    \section1 Loading QML Components
-
-    Reusing the RemoveButton itself is very simple.  When parsing a QML file
-    if a Component is referred to that isn't already in the system, Qt
-    will try to load it from a file of the same name with the ".qml" extension.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/1/ContactField.qml load
-
-    The above QML code will attempt to load the RemoveButton component from
-    a file with the name "RemoveButton.qml" from the following search paths.
-
-    \list
-    \o Any imported directories. These are listed at the start of the file using
-        \c { import "path" }.
-    \o the directory of the QML code file
-    \endlist
-
-    All the properties of the button are
-    accessible and can be overridden from defaults.  The loaded component
-    can also refer to elements further up in the tree, so that code within
-    RemoveButton.qml could refer to the contactField component.
-    Only properties of the top level element in RemoveButton.qml are visible to
-    the contact field.
-
-    There are also two other ways to reuse components in QML.  A component
-    can be reused from within the same QML file using Component and Loader
-    elements.  The next code snippet produces three red rounded rectangles
-    within a large blue rectangle.
-
-    \image declarative-reuse-bluerect.png
-
-    \snippet declarative/tutorials/contacts/2_Reuse/1b/BlueRect.qml all
-
-    This can be useful when the component is not complex enough to justify its
-    own file.  The third way to reuse components allows for delaying loading
-    of the QML until some later event.  \l{Loader}{Loader} includes
-    a special child, item, which has its definition provided by the
-    contents of the source property of the loader.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/1a/ContactField.qml load
-
-    This last method is useful if the contents of a item need to change at
-    run time or if the initial complexity of the loaded QML needs to be
-    reduced in order to improve the time it takes to start the application. In
-    chapter three this method is used to improve performance of
-    scrolling through very large numbers of items.
-
-    Because of its simplicity, the first method is the recommended in most
-    cases and will be the focus of the remainder of this chapter.
-
-    \section1 Properties and Signals
-
-    The next task is to be able to control aspects of the RemoveButton from
-    the components that use it.  In particular controlling how far it
-    expands and how it reacts when the user clicks on the confirm icon
-    of the remove button.  When reusing a component in a separate QML file
-    only the attributes of the root element are visible.  To allow controlling
-    attributes of child elements within an imported component we need to define
-    some properties and signals for the RemoveButton.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/2/RemoveButton.qml define properties and signals
-
-    The children of the remove button can use these properties and signals.  The
-    opened state can now bind the expanded width to the expandedWidth property.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/2/RemoveButton.qml use width
-
-    Also when the confirm icon is clicked, as well as toggling the state it will
-    emit the confirmed signal of the RemoveButton component.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/2/RemoveButton.qml use signal
-
-    These properties and signals can also be accessed from the contact field the same
-    way standard system component properties and signals are accessed.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/2/ContactField.qml use properties and signals
-
-    Now when the remove button is expanded, it will expand to the width of the
-    contact field.  Also when the user confirms the remove action, the
-    text section of the contact field will be cleared.
-
-    \section1 States
-
-    Its also possible to access the state of included components.  The FieldText
-    component we will use in this tutorial is also been written specifically
-    for our contacts application.  In
-    this case we want it to expand when editing.  One way to do this would
-    be to anchor the field text component to the center of its parent and
-    then let its own width change push the remove button away, however that
-    would make it difficult to have the remove button also push the field
-    text to the left when the remove button expands.  Instead we will anchor
-    the right edge of the field text to the left edge of the remove button
-    and use a state change in the contact field itself to move the
-    remove button and the field icon out of
-    view.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/3/ContactField.qml all
-
-    Apart from accessing the fieldText.state, the above code also uses the when
-    attribute of its own editingText state.  This is an alternative to using
-    a signal to change state.  When the value of the expression for the
-    when attribute changes, Qt will detect if the contactField needs to enter
-    that state.  In the FieldText element a similar approach is used to fade
-    out the label of the FieldText when the user enters some text of their own.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/3/FieldText.qml behavior
-
-    \c{fieldText} is the enclosing component and \c{textEdit} is a TextEdit element
-    provided by Qt.  In the QML code above, the opacity of the textLabel is
-    only 1 if the text for the textEdit is empty.  This is a form of
-    short cut to using states for an element, useful if only one property
-    is changing as it is for the textLabel.  To animate a property change is
-    similar to animating a state change.  Using the Behavior element we can
-    specify how the property changes if it does change state, allowing for
-    a smooth transition.
-
-    \section1 Key and Mouse Focus
-
-    Setting focus to true on a component does not always mean
-    that the component has focus.  This is due to the declarative nature
-    of QML, and can be affected by multiple components both indicating
-    focus to be true.  At the time of writing this tutorial both key and mouse
-    focus handling are still being improved.  Hence we will only lightly cover
-    the topic.
-
-    For an item to have key focus in QML it is required that:
-
-    \list
-    \o If there is a FocusScope ancestor of the component that it has focus as well.
-    \o That it is the most recent component within the focus realms descendent's
-        to receive focus
-    \endlist
-
-    The read-only property focus can be used to determine whether a
-    component will receive key input.  Any un-handled keys will be passed to
-    the components parent, which in turn will pass keys it doesn't handle up to its
-    own ancestors.
-
-    Some components such as ListView components are also FocusScope components, as they
-    handle focus among the child list items.
-
-    At this stage of the tutorial it is sufficient to use the setting of 'focus'
-    as we only have a list of line edits and only one should be active at any given time.
-
-    Currently if multiple contact fields were put into our contact editor,
-    any of the FieldText components could be clicked and opened, and
-    any of the RemoveButton components could be clicked and opened, all
-    at the same time.  This leads to situations where the users actions
-    are ambiguous
-
-    \image declarative-reuse-focus.png
-
-    To counteract this we will add a property of the root element to indicate
-    when an element has 'grabbed' mouse interaction, preventing other
-    clickable elements from reacting.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/4/Contact.qml grab property
-
-    The code that we want to disable then simply needs to check this property before
-    acting.
-
-    \snippet declarative/tutorials/contacts/2_Reuse/4/RemoveButton.qml grab
-
-    \note Handling Key and Mouse focus in QML is quite likely to change before
-    the Qt 4.6 release.
-*/
-
-/*!
-    \page tutorials-declarative-contacts-part3.html
-    \contentspage {Declarative UI Tutorial}{Contents}
-    \previouspage {tutorials/declarative/contacts/part2}{Chapter 2}
-    \example tutorials/declarative/contacts/part3
-    \title Models, Views and Delegates
-    \tableofcontents
-
-    In the previous chapters we designed a component to display and
-    edit a contact.  The next step is to display a list of those contacts
-    and allow the user to expand individual contacts for editing.
-
-    As the previous elements will not be changed in this section, they have
-    been moved to a lib directory for this tutorial and the relevant
-    import path has been used.
-
-    \section1 Simple List View
-
-    Displaying lists requires three components.  A model that holds the
-    data displayed, a delegate to indicate how elements are drawn and
-    a view to arrange the elements.
-
-    \image declarative-tutorial-list.gif
-
-    For the purposes of this tutorial we will be using an SQL query as our
-    data model.  This can be declared in the resources section of
-    the parent item.
-
-    \snippet declarative/tutorials/contacts/3_Collections/1/ContactView.qml model
-
-    The SqlConnection component describes how to connect to the database in
-    much the same ways as the QSqlDatabase::addDatabase() function is used.
-    In this case an SQLite database is used as it can be connected to as a
-    file, reducing complexity in setting up a database server or credentials.
-
-    The SqlQuery component allows various forms of queries to be described.
-    When the query is a select statement, the component also acts as a model
-    allowing it to provide data to a ListView component.  The query above
-    retrieves the fields recid, label, email and phone from a contacts table,
-    and orders the results by the label of the contact first, and then by
-    the recid for any contacts with equivalent labels.
-
-    The ListView component is suitable for displaying models and is declared
-    much like any other QML component.  The ListView component also has
-    a delegate property that defines how to construct components for items in the list.
-
-    \snippet declarative/tutorials/contacts/3_Collections/1/ContactView.qml delegate
-
-    Unlike a child element, this describes a template on how to build the component
-    for each element, much in the same way that components are loaded from
-    files such as RemoveButton.qml.  The are constructed or destroyed as items
-    scroll into our out of the visible area of the list.
-
-    The entire view component will look like:
-
-    \snippet declarative/tutorials/contacts/3_Collections/1/ContactView.qml view
-
-    This gives us a list of contacts that the user can flick through.
-
-    \section1 Animating Delegates
-
-    The next step is to allow the user to click on a contact to edit the
-    contact.  We will take advantage of QML to open a Contact component
-    in the list rather than as a new dialog or view.  This is very
-    similar to how the contents of the FieldText and RemoveButton components
-    are swapped in and out.
-
-    \image declarative-tutorial-list-open.gif
-
-    \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml components
-
-    The first step is to have two children of our delegate component that can
-    be swapped between.  The plain Text component and the Contact component built
-    in the previous chapters.  We also add a MouseRegion that can be clicked upon
-    to change the state of the delegate component.
-
-    \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml states
-
-    This defines the open state of the delegate.  It changes the height of the delegate
-    component to that of the whole list view, pushing the other items off each end of
-    the list.  It sets the listview's scroll viewportY of the ListView to the
-    y value of the delegate so that the top of the delegate matches the top of the list view.
-    The next step is to lock the list view.  This prevents the user being able to flick
-    the list view. The final to properties that are set should
-    be familiar from previous chapters, setting the opacity of the items such
-    that the new item is visible and the old item hidden.
-
-    We then add a transition so that this becomes animated:
-
-    \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml transitions
-
-    This allows the user to click on an item to enter the open state.  Elsewhere on our
-    contact view we add a button so that the user can leave the detailed view of the contact.
-
-    \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml button
-
-    And connect it's clicked value to some script to set the state of the delegate
-    back to its default state.
-
-    \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml connections
-
-    Something worth noting at this point is that every delegate created has this connection.
-    It is important to check whether the delegate is the one in the open state, and
-    taking some effort to ensure only one is, before acting on the signal from the button.
-
-    \section1 Performance Considerations
-
-    We have now made a contact application that can view a list of contacts, open one,
-    and close it again.  Its now time to take a moment and consider the implications
-    of a list view delegate.  It is created for each and every item in the list,
-    and while the list cleans up after itself and only has delegate components constructed
-    for visible items and any single point of animation, the list can scroll very quickly.
-    This means potentially thousands of delegate components will be constructed and
-    destroyed when the user is flicking through the list.
-
-    Its important then to try and minimize the complexity of the delegate.  This
-    can be done by delaying the loading of the component.  By using the qml property
-    of the \l{Item}{Item} component, we can delay building the Contact.qml item until the user
-    attempts to open the list.
-
-    \snippet declarative/tutorials/contacts/3_Collections/3/ContactView.qml setting qml
-
-    \l{Loader}{Loader} has a source property that represents the filename for the contents of
-    a special item child of the \l{Loader}{Loader}.  By setting the source property of the Details
-    component on clicking the mouse region, the more complex component isn't loaded
-    until needed.  The down side about this though is the properties of Contact
-    cannot be set until the item is loaded.  This requires using the Bind element.
-
-
-    \snippet declarative/tutorials/contacts/3_Collections/3/ContactView.qml binding
-
-    Unlike binding a value to the property of a component directly, the Bind element
-    allows both the target and the property set to themselves be to dynamic values.
-    This means that when the source property is set, it will change the
-    item property of the Details component.  This in turn triggers the Bind
-    elements to set the required properties of the item, which is now
-    an instance of the Contact component.
-*/