Doc - using Qt Quick Designer to create components

Task-number: QTCREATORBUG-2661

Reviewed-by: Thomas Hartmann

4 files changed, 299 insertions, 8 deletions

diff --git a/doc/images/qmldesigner-borderimage.png b/doc/images/qmldesigner-borderimage.png
index 3fc10dfe0e..c28386bd47 100644
--- a/doc/images/qmldesigner-borderimage.png
+++ b/doc/images/qmldesigner-borderimage.png
diff --git a/doc/images/qmldesigner-states.png b/doc/images/qmldesigner-states.png
new file mode 100644
index 0000000000..7e222e8812
--- /dev/null
+++ b/doc/images/qmldesigner-states.png
diff --git a/doc/images/qmldesigner-visual-editor.png b/doc/images/qmldesigner-visual-editor.png
index 2bb23b8401..5813c83027 100644
--- a/doc/images/qmldesigner-visual-editor.png
+++ b/doc/images/qmldesigner-visual-editor.png
diff --git a/doc/qtcreator.qdoc b/doc/qtcreator.qdoc
index c650e44041..e6f6718ec8 100644
--- a/doc/qtcreator.qdoc
+++ b/doc/qtcreator.qdoc
@@ -1024,10 +1024,6 @@
     editor. Then select the \gui {Design} mode to edit the file in the
     visual editor.
 
-    \note The visual \QMLD editor is provided as an experimental plugin that you must
-    enable to be able to edit QML files in the \gui Design mode. Enabling the
-    visual editor can negatively affect the overall stability of Qt Creator.
-
     To enable or disable the \QMLD visual editor, select
     \gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
     to enable or disable the visual editor.
@@ -1038,8 +1034,10 @@
 
     \list
 
-    \o \gui {Navigator} pane displays the items in the scene. You can
+    \o \gui {Navigator} pane displays the items in the editor. You can
     show and hide items to focus on specific parts of the application.
+    To view lists of files or projects, instead, select \gui {File System},
+    \gui {Open Documents}, or \gui Projects in the menu.
 
     \o \gui {Library} pane displays lists of predefined \gui {Items} and
     imported \gui {Resources} that you can use to design applications. The
@@ -6320,9 +6318,9 @@
 /*!
 
     \contentspage index.html
-    \previouspage quick-projects.html
+    \previouspage creator-using-qt-quick-designer.html
     \page quick-components.html
-    \nextpage quick-screens.html
+    \nextpage quick-buttons.html
 
     \title Creating Components
 
@@ -6331,7 +6329,7 @@
     through properties, signals, and slots, and is generally defined in its own QML file.
     You can import components to screens and applications.
 
-    You can create the following QML components:
+    You can use the following QML elements to create components:
 
     \list
 
@@ -6355,6 +6353,268 @@
 
     \endlist
 
+    \section1 Creating Components in Qt Quick Designer
+
+    \list 1
+
+        \o Select \gui {File > New File or Project > Files and Classes > QML
+        > Choose...} to create a new .qml file.
+
+        \o Click \gui Design to open the .qml file in \QMLD.
+
+        \o Drag and drop an item from the \gui Library pane to the editor.
+
+        \o Edit item properties in the \gui Properties pane.
+
+        The available properties depend on the item.
+
+    \endlist
+
+    The following sections contain examples of how to create some common components:
+
+    \list
+
+        \o \l{Creating Buttons}
+
+        \o \l{Creating Scalable Buttons and Borders}
+
+    \endlist
+
+*/
+
+
+/*!
+    \contentspage index.html
+    \previouspage quick-components.html
+    \page quick-buttons.html
+    \nextpage quick-scalable-image.html
+
+    \title Creating Buttons
+
+    To create a button component:
+
+    \list 1
+
+        \o Select \gui {File > New File or Project > QML > QML File > Choose...} to
+         create a QML file called Button.qml (for example).
+
+        \note Components are listed in the \gui Library pane only if the filename
+        begins with a capital letter.
+
+        \o Click \gui {Design} to edit the file in the visual editor.
+
+        \o In the \gui Navigator pane, click \gui Rectangle to set properties
+        for it.
+
+        \o In the \gui Properties pane, modify the appearance of the button.
+
+        \list a
+
+            \o In the \gui Size field, set the width (\gui W) of the button to 60
+             and the height of the button (\gui H) to 20.
+
+            \o In the \gui Color field, select the button color.
+
+            \o In the \gui Radius field, use the slider to set the radius of the
+            rectangle and produce rounded corners for the button.
+
+        \endlist
+
+        \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
+        creates a nested element where \gui Rectangle is the parent element of
+        \gui Text. Elements are positioned relative to their parents.
+
+        \o In the \gui Properties pane, edit the properties of the \gui Text item.
+
+        \list a
+
+            \o In the \gui Text field, type \bold Button.
+
+            You can select the text color, font, size, and style in the \gui Font
+            section.
+
+            \o In the \gui Alignment field, select the center buttons to align
+            the text to the center of the button.
+
+            \o Click \gui {Layout}, and then click the
+            \inlineimage qmldesigner-anchor-fill-screen.png
+            button to anchor the text to the whole button area.
+
+        \endlist
+
+        \o Press \key {Ctrl+S} to save the button.
+
+        \image qmldesigner-button.png "Button component"
+
+    \endlist
+
+    \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
+    project.
+
+    To create a graphical button that scales beautifully without using vector graphics,
+    use the \l{http://doc.qt.nokia.com/4.7-snapshot/qml-borderimage.html}{Border Image}
+    element. For more information, see \l{Creating Scalable Buttons and Borders}.
+
+    */
+
+
+    /*!
+
+    \contentspage index.html
+    \previouspage quick-buttons.html
+    \page quick-scalable-image.html
+    \nextpage quick-screens.html
+
+    \title Creating Scalable Buttons and Borders
+
+    You can use the \l{http://doc.qt.nokia.com/4.7-snapshot/qml-borderimage.html}{Border Image}
+    element to display an image, such as a PNG file, as a border and a background.
+
+    Use two Border Image elements and suitable graphics to make it look like the button
+    is pushed down when it is clicked. One of the Border Image elements is visible by default.
+    You can specify that it is hidden and the other one becomes visible when the mouse
+    is clicked.
+
+    Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
+    when it detects a mouse click.
+
+    You can add text to the button and set it up as a property. The text can then be initialized
+    from the outside, making the button a reusable UI component. The font size is also available
+    in case the default size is too big. You can scale down the button text and use smooth text
+    rendering for some extra quality.
+
+    \image qmldesigner-borderimage.png "Graphical button"
+
+    To create a graphical button:
+
+    \list 1
+
+        \o Select \gui {File > New File or Project > QML > QML File > Choose...} to create
+        a QML file called Button.qml (for example).
+
+        \o Double-click the file to open it in the code editor.
+
+        \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
+        following code snippet:
+
+        \code
+
+        Item {
+
+        }
+
+        \endcode
+
+        \o Specify properties and set expressions for the \gui Item, as
+        illustrated by the following code snippet:
+
+        \code
+
+        property string text: ""
+        property int fontSize: 44
+
+        signal clicked
+
+        \endcode
+
+        You will point to the properties and expression later.
+
+        \o Click \gui {Design} to edit the file in the visual editor.
+
+        \o Drag and drop two \gui BorderImage items from the \gui Library pane to
+        the scene.
+
+        \o Drag and drop a \gui Text item to the scene.
+
+        \o Drag and drop a \gui MouseArea to the screen.
+
+        \o Click \gui Design to return to the visual editor.
+
+        \o In the \gui Navigator pane, select \gui border_image1 to specify
+        settings for it in the \gui Properties pane:
+
+        \list a
+
+            \o Select \gui {Set Expression} in the menu next to the \gui Visibility
+            check box.
+
+            \o Enter the following expression to specify that the image is visible
+            when the mouse is not pressed down: \c {!mouse_area1.pressed}.
+
+            \o In the \gui Source field, select the image file for the
+            button, for example button_up.png.
+
+            \o Click \gui {Layout}, and then click the
+            \inlineimage qmldesigner-anchor-fill-screen.png
+            button to anchor the border image to the \gui Item.
+
+        \endlist
+
+        \o Select \gui border_image2 to specify similar settings for it:
+
+        \list a
+
+            \o Set the following epression for \gui Visibility, to specify that
+            the the image is visible when the mouse is pressed down:
+            \c {mouse_area1.pressed}.
+
+            \o In the \gui Source field, select the image file for the
+            button when it is clicked, for example button_down.png.
+
+            \o Click \gui {Layout}, and then click the
+            \inlineimage qmldesigner-anchor-fill-screen.png
+            button to anchor the border image to the \gui Item.
+
+        \endlist
+
+        \o Select \gui text1 to specify font size and color, and text
+        scaling and rendering:
+
+        \list a
+
+            \o In the \gui Color field, use the color picker to select
+            the font color, or enter a value in the field.
+
+            \o In the \gui Text field, select \gui {Set Expression} and
+            enter a pointer to the \c {text} property that you specified
+            earlier: \c {parent.txt}.
+
+            \o Select the \gui Aliasing check box to enable smooth text
+            rendering.
+
+            \o In the \gui Size field, select \gui {Pixels} to specify
+            the font size in pixels. By default, the size is specified in
+            points.
+
+            \o In the \gui Size field, select \gui {Set Expression} and
+            enter a pointer to the \c {fontSize} property that you specified
+            earlier.
+
+            \o Click \gui {Layout}, and then click the
+            \inlineimage qmldesigner-center-in.png "Anchor buttons"
+            buttons to inherit the vertical and horizontal centering from
+            the parent.
+
+            \o Click \gui Advanced to specify scaling for the text in the
+            \gui Scale field.
+
+            \o Select \gui {Set Expression} and enter the following expression:
+            \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.
+
+            \note You can enter long and complicated expressions also in the
+            code editor.
+
+        \endlist
+
+        \o In the code editor, add to the \c MouseArea item
+        a pointer to the \c clicked expression that you added earlier:
+        \c {onClicked: parent.clicked()}.
+
+    \endlist
+
+    \note To view the button, you must add it to a Qt Quick Application or Qt
+    Quick UI project.
+
 */
 
 
@@ -6368,6 +6628,28 @@
     \title Creating Screens
 
     You can use predefined QML elements and your own components to create screens.
+    Typically, the main qml file in a Qt Quick project specifies the main window of an
+    application.
+
+    \section1 Adding Components to Screens
+
+    \list 1
+
+        \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick UI}
+        or \gui {Qt Quick Application} to create a Qt Quick project.
+
+        \o Drag and drop components from the \gui Library pane to the editor.
+
+        The QML files in the project folder are displayed in \gui {QML Elements}.
+
+        \o Select components in the \gui Navigator pane to edit their properties
+        in the \gui Properties pane.
+
+        For example, you can anchor components to a position on the screen.
+
+    \endlist
+
+    \section1 Organizing Items on Screens
 
     You can create the following types of views to organize items provided by
     \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:
@@ -6382,6 +6664,8 @@
 
     In the code editor, write the code to use the data models.
 
+    \section1 Using States
+
     Use states and transitions
     to navigate between screens.
 
@@ -6389,6 +6673,13 @@
     their properties and behavior and the available actions. For example, you can use
     states to create two screens.
 
+    To add states, click the empty slot in the \gui States pane. Then modify the new state
+    in the visual editor.
+
+    \image qmldesigner-states.png "States pane"
+
+    The properties that you change in a state are highlighted with blue color.
+    In the code editor, you can see the changes recorded as changes to the base state.
 */