Doc: using UI forms in Qt Quick Designer

New concept in Qt Creator 3.3 and  Qt 5.4.

Change-Id: I24cacd4c98bb6873625d5cda44a78d5ba0ad8f5b
Reviewed-by: Tim Jenssen <tim.jenssen@digia.com>
Reviewed-by: Thomas Hartmann <Thomas.Hartmann@digia.com>

doc/src/qtquick/qtquick-app-development.qdoc

@@ -36,6 +36,13 @@
         \li \l {Creating Qt Quick Projects}
 
             You can use wizards to create Qt Quick projects.
+
+        \li \l{Qt Quick UI Forms}
+
+            Some of the wizards create Qt Quick projects that contain UI forms
+            (.ui.qml files). The forms use a purely declarative subset of the
+            QML language and you can edit them in the Design mode.
+
         \li \l {Using Qt Quick Designer}
 
             You can use the code editor (Edit mode) or the visual editor (Design

doc/src/qtquick/qtquick-creating.qdoc

@@ -27,7 +27,7 @@
     \contentspage {Qt Creator Manual}
     \previouspage creator-visual-editor.html
     \page quick-projects.html
-    \nextpage creator-using-qt-quick-designer.html
+    \nextpage creator-quick-ui-forms.html
 
     \title Creating Qt Quick Projects
 
@@ -102,6 +102,13 @@
         \li .qml file defines an UI item, such as a component, screen, or the
             whole application UI.
 
+        \li .qml.ui files defines a form for the application UI. It is created
+            if you select \gui {Qt Quick Controls 1.3}, or later, or
+            \gui {Qt Quick 2.4}, or later. The forms can contain a subset of the
+            QML language. Similarly as with the UI forms for \QD, it is
+            recommended that you use \QMLD to edit the UI forms. For more
+            information, see \l{Qt Quick UI Forms}.
+
     \endlist
 
     To use JavaScript and image files in the application, copy them to the

doc/src/qtquick/qtquick-designer.qdoc

@@ -24,16 +24,15 @@
 
 /*!
     \contentspage {Qt Creator Manual}
-    \previouspage quick-projects.html
+    \previouspage creator-quick-ui-forms.html
     \page creator-using-qt-quick-designer.html
     \nextpage quick-components.html
 
     \title Using Qt Quick Designer
 
-    You can edit .qml files in the \QMLD visual editor or in the code editor.
-
-    In \gui Projects, double-click a .qml file to open it in the code editor.
-    Then select the \gui {Design} mode to edit the file in the visual editor.
+    You can edit \l{Qt Quick UI Forms} (ui.qml files) in \QMLD. \QC opens the
+    UI forms in the \gui Design mode. It is recommended that you use UI forms
+    for components that you want to desing in \QMLD.
 
     \image qmldesigner-visual-editor.png "Visual editor"
 
@@ -185,7 +184,8 @@
     values that you specify explicitly are highlighted with blue color. In
     addition, property changes in states are highlighted with blue.
 
-    This allows you to easily see which values are set in the .qml file and
+    This allows you to easily see which values are set in the UI form or
+    QML file and
     which values are default characteristics of a QML type or a component.
 
     When editing states, you can easily see which values are explicitly set in
@@ -201,7 +201,7 @@
     \image qmldesigner-properties-explicit-state1.png "Explicitly set properties"
 
     Resetting a property sets it back to the default value and removes the value
-    from the .qml file.
+    from the UI form or QML file.
 
     \note As a result, all boolean values can be visualized in four different
     ways.

doc/src/qtquick/qtquick-ui-forms.qdoc

@@ -0,0 +1,105 @@
+/****************************************************************************
+**
+** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of Qt Creator
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+**
+****************************************************************************/
+
+// **********************************************************************
+// NOTE: the sections are not ordered by their logical order to avoid
+// reshuffling the file each time the index order changes (i.e., often).
+// Run the fixnavi.pl script to adjust the links to the index order.
+// **********************************************************************
+
+/*!
+
+    \contentspage {Qt Creator Manual}
+    \previouspage quick-projects.html
+    \page creator-quick-ui-forms.html
+    \nextpage creator-using-qt-quick-designer.html
+
+    \title Qt Quick UI Forms
+
+    You can use \QC wizards to create UI forms tha have the filename extension
+    \e .ui.qml. The UI forms contain a purely declarative subset of the QML
+    language. It is recommended that you edit the forms in the \gui Design mode.
+    \QC enforces the use of the supported QML features by displaying error
+    messages.
+
+    The following features are not supported:
+
+    \list
+        \li JavaScript blocks
+        \li Function definitions
+        \li Function calls (except \c qsTr)
+        \li Other bindings than pure expressions
+        \li Signal handlers
+        \li States in other items than the root item
+        \li Root items that are not derived from \l QQuickItem or \l Item
+    \endlist
+
+    The following types are not supported:
+
+    \list
+        \li Behavior
+        \li Binding
+        \li Canvas
+        \li Component
+        \li Shader Effect
+        \li Timer
+        \li Transform
+        \li Transition
+    \endlist
+
+    \section1 Using Qt Quick UI Forms
+
+    You can edit the forms in the \gui Design mode. Items that are supposed to
+    be used in QML code have to be exported as properties:
+
+    \code
+    Item {
+        width: 640
+        height: 480
+
+        property alias button: button
+
+        Button {
+            anchors.centerIn: parent
+            id: button
+            text: qsTr("Press Me")
+        }
+    }
+    \endcode
+
+    The property alias exports the button to the QML code that uses the form.
+    In \QC Enterprise you can use the
+    \inlineimage qmldesigner-export-item-button.png
+    (\gui Export) button in the \gui Navigator to export an item as a property:
+
+    \image qmldesigner-export-item.png
+
+    In the QML file that uses the form, you can use the \c button property alias
+    to implement signal handlers, for example. In the following code snippet,
+    the UI form is called \e MainForm.ui.qml:
+
+    \code
+    MainForm {
+        anchors.fill: parent
+        button.onClicked: messageDialog.show(qsTr("Button pressed"))
+    }
+    \endcode
+
+    You can also assign properties or define behavior or transitions.
+
+*/