From 9a7f4cae005a66c0f2525b1b975618b2b3e48dd6 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 28 Oct 2014 15:18:01 +0100 Subject: [PATCH] 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 Reviewed-by: Thomas Hartmann --- doc/src/qtcreator.qdoc | 1 + doc/src/qtquick/qtquick-app-development.qdoc | 7 ++ doc/src/qtquick/qtquick-creating.qdoc | 9 +- doc/src/qtquick/qtquick-designer.qdoc | 14 +-- doc/src/qtquick/qtquick-ui-forms.qdoc | 105 +++++++++++++++++++ 5 files changed, 128 insertions(+), 8 deletions(-) create mode 100644 doc/src/qtquick/qtquick-ui-forms.qdoc diff --git a/doc/src/qtcreator.qdoc b/doc/src/qtcreator.qdoc index fdb28a2ef80..319f9d8e2b8 100644 --- a/doc/src/qtcreator.qdoc +++ b/doc/src/qtcreator.qdoc @@ -165,6 +165,7 @@ \li \l{Developing Qt Quick Applications} \list \li \l {Creating Qt Quick Projects} + \li \l {Qt Quick UI Forms} \li \l {Using Qt Quick Designer} \li \l {Creating Components} \li \l {Creating Buttons} diff --git a/doc/src/qtquick/qtquick-app-development.qdoc b/doc/src/qtquick/qtquick-app-development.qdoc index c54a0654982..f1a678775e9 100644 --- a/doc/src/qtquick/qtquick-app-development.qdoc +++ b/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 diff --git a/doc/src/qtquick/qtquick-creating.qdoc b/doc/src/qtquick/qtquick-creating.qdoc index 0f4ce96f2be..cb4b02589b4 100644 --- a/doc/src/qtquick/qtquick-creating.qdoc +++ b/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 diff --git a/doc/src/qtquick/qtquick-designer.qdoc b/doc/src/qtquick/qtquick-designer.qdoc index cc8b45025ea..7fe5db8b9a0 100644 --- a/doc/src/qtquick/qtquick-designer.qdoc +++ b/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. diff --git a/doc/src/qtquick/qtquick-ui-forms.qdoc b/doc/src/qtquick/qtquick-ui-forms.qdoc new file mode 100644 index 00000000000..7a3e1db1121 --- /dev/null +++ b/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. + +*/