Doc: Update topic on using Border Image to create buttons

Change-Id: Iaea732121a5dfbad9f5791efd47f947d0c0e6045
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>

10 files changed, 141 insertions, 152 deletions

diff --git a/doc/qtcreator/images/qmldesigner-borderimage-bindings-text.png b/doc/qtcreator/images/qmldesigner-borderimage-bindings-text.png
deleted file mode 100644
index 9a1e47c52d..0000000000
--- a/doc/qtcreator/images/qmldesigner-borderimage-bindings-text.png
+++ /dev/null
diff --git a/doc/qtcreator/images/qmldesigner-borderimage-bindings.png b/doc/qtcreator/images/qmldesigner-borderimage-bindings.png
index 1955f74567..45e01ed3f0 100644
--- a/doc/qtcreator/images/qmldesigner-borderimage-bindings.png
+++ b/doc/qtcreator/images/qmldesigner-borderimage-bindings.png
diff --git a/doc/qtcreator/images/qmldesigner-borderimage-bindings1.png b/doc/qtcreator/images/qmldesigner-borderimage-bindings1.png
new file mode 100644
index 0000000000..46ac245c46
--- /dev/null
+++ b/doc/qtcreator/images/qmldesigner-borderimage-bindings1.png
diff --git a/doc/qtcreator/images/qmldesigner-borderimage-connections.png b/doc/qtcreator/images/qmldesigner-borderimage-connections.png
deleted file mode 100644
index caaa7a7236..0000000000
--- a/doc/qtcreator/images/qmldesigner-borderimage-connections.png
+++ /dev/null
diff --git a/doc/qtcreator/images/qmldesigner-borderimage-properties.png b/doc/qtcreator/images/qmldesigner-borderimage-properties.png
deleted file mode 100644
index 9f8628eba1..0000000000
--- a/doc/qtcreator/images/qmldesigner-borderimage-properties.png
+++ /dev/null
diff --git a/doc/qtcreator/images/qmldesigner-borderimage-states.png b/doc/qtcreator/images/qmldesigner-borderimage-states.png
new file mode 100644
index 0000000000..f25290fa4b
--- /dev/null
+++ b/doc/qtcreator/images/qmldesigner-borderimage-states.png
diff --git a/doc/qtcreator/images/qmldesigner-borderimage-type.png b/doc/qtcreator/images/qmldesigner-borderimage-type.png
new file mode 100644
index 0000000000..cf287390c5
--- /dev/null
+++ b/doc/qtcreator/images/qmldesigner-borderimage-type.png
diff --git a/doc/qtcreator/images/qmldesigner-borderimage.png b/doc/qtcreator/images/qmldesigner-borderimage.png
index d766161fb0..82878baa90 100644
--- a/doc/qtcreator/images/qmldesigner-borderimage.png
+++ b/doc/qtcreator/images/qmldesigner-borderimage.png
diff --git a/doc/qtcreator/images/qmldesigner-button.png b/doc/qtcreator/images/qmldesigner-button.png
index faf511fb63..6af7d03ee3 100644
--- a/doc/qtcreator/images/qmldesigner-button.png
+++ b/doc/qtcreator/images/qmldesigner-button.png
diff --git a/doc/qtcreator/src/qtquick/qtquick-buttons.qdoc b/doc/qtcreator/src/qtquick/qtquick-buttons.qdoc
index 54ad29ee8a..367843d918 100644
--- a/doc/qtcreator/src/qtquick/qtquick-buttons.qdoc
+++ b/doc/qtcreator/src/qtquick/qtquick-buttons.qdoc
@@ -60,9 +60,9 @@
             \uicontrol Properties view.
 
         \li Drag and drop a \uicontrol Rectangle from the \uicontrol Library to
-            the item in the navigator. This creates a nested item where the
-            item is the parent of the rectangle. Items are positioned relative
-            to their parents.
+            the item in \uicontrol Navigator. This creates a nested item where
+            the item is the parent of the rectangle. Items are positioned
+            relative to their parents.
 
         \li In the \uicontrol Properties view, modify the appearance of the
             rectangle:
@@ -71,8 +71,8 @@
 
             \li In the \uicontrol Color field, select the button color.
 
-            \li In the \uicontrol Radius field, use the slider to set the radius of
-                the rectangle and produce rounded corners for the button.
+            \li In the \uicontrol Radius field, set the radius of
+                the rectangle to produce rounded corners for the button.
 
             \li Select \uicontrol {Layout}, and then select the
                 \inlineimage anchor-fill.png
@@ -82,14 +82,15 @@
 
         \endlist
 
-        \li Drag and drop a \uicontrol {Text} type to the item in the navigator.
+        \li Drag and drop a \uicontrol {Text} type to the item in
+            \uicontrol Navigator.
 
         \li In the \uicontrol Properties view, edit the properties of the \uicontrol Text
             type.
 
         \list a
 
-            \li In the \uicontrol Text field, type \b Button.
+            \li In the \uicontrol Text field, enter \e Button.
 
                 You can select the text color in the \uicontrol {Text color} field and the
                 font, size, and style in the
@@ -109,10 +110,17 @@
 
     \endlist
 
+    To be useful, the button type has to be created in a project.
+    When you work on other QML files in the project to create screens
+    or other components for the UI, the button type appears in the
+    \uicontrol {My QML Components} tab of the \uicontrol Library view.
+    You can use it to create button instances and modify their properties
+    to assign them useful IDs, change their appearance, and set the button
+    text for each button instance, for example.
+
     To create a graphical button that scales beautifully without using vector
     graphics, use the \l [QML]{BorderImage}{Border Image} type. For more
     information, see \l{Creating Scalable Buttons and Borders}.
-
     */
 
 
@@ -126,166 +134,147 @@
     You can use the \l [QML]{BorderImage}{Border Image} type to display an
     image, such as a PNG file, as a border and a background.
 
-    Use two border images and suitable graphics to make it look like the
-    button is pushed down when it is clicked. One of the border images
-    is visible by default. You can specify that it is hidden and the other one
-    becomes visible when the mouse is clicked.
+    Use two border images and suitable graphics to change the appearance of
+    a button when it is clicked. You can use use \l{Adding States}{states}
+    to determine which image is visible depending on whether the mouse
+    button is pressed down. You could add more images and states to
+    change the appearance of the button depending on other mouse events,
+    such as hovered.
 
     Add a \l [QML]{MouseArea}{Mouse Area} type that covers the whole area and
-    emits the clicked signal (\c {item.clicked()}) when it detects a mouse
-    click.
+    reacts to mouse events.
 
-    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.
+    You can use states also to change the button text color and font size. For
+    example, you can scale the button text up or down.
 
-    \image qmldesigner-borderimage.png "Graphical button"
+    \image qmldesigner-borderimage-type.png "Button type in Form Editor and States"
 
-    To create a graphical button:
+    \section1 Creating the Button Type
 
-    \list 1
+    To create a button type, select \uicontrol File >
+    \uicontrol {New File or Project} >
+    \if defined(qtcreator)
+    \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} >
+    \else
+    \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick File} >
+    \endif
+    \uicontrol Choose to create a QML file called Button.qml (for example).
 
-        \li Select \uicontrol File > \uicontrol {New File or Project} >
-            \if defined(qtcreator)
-            \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} >
-            \else
-            \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick File} >
-            \endif
-            \uicontrol Choose to create a QML file called Button.qml (for
-            example).
+    \note Types are listed in the \uicontrol Library only if the
+    filename begins with a capital letter.
 
-            \note Types are listed in the \uicontrol Library only if the
-            filename begins with a capital letter.
+    \section1 Constructing the Button Component
 
-        \li Click \uicontrol {Design} to edit the file in the
-            \uicontrol {Form Editor}.
+    To construct the button component:
 
-        \li In the \uicontrol Navigator, select \uicontrol Item and set the
+    \list 1
+        \li Click \uicontrol {Design} to edit the QML file in the
+            \uicontrol {Form Editor}.
+        \li In the \uicontrol {Assets} tab of \uicontrol Library, select
+            \uicontrol {Add New Assets} to copy the image files you want
+            to use to the project folder.
+        \li In the \uicontrol Navigator, select the root item and set the
             width (\uicontrol W) and height (\uicontrol H) of the button in the
-            \uicontrol Properties view.
-
-        \li Select \uicontrol Connections > \uicontrol {Properties} >
-            \uicontrol Add to add properties for the item:
-
-            \image qmldesigner-borderimage-properties.png "Properties"
-
+            \uicontrol Properties view to match the size of the images
+            you plan to use. This specifies the initial size of the button
+            component.
+        \li Drag and drop two \uicontrol {Border Image} types from
+            \uicontrol Library to the root item in \uicontrol Navigator.
+        \li Drag and drop a \uicontrol Text type to the root item.
+        \li Drag and drop a \uicontrol {Mouse Area} to the root item in
+            \uicontrol Navigator.
+        \li Select a border image to edit the values of its properties:
             \list a
-
-                \li Double-click in the columns in the view to specify a \c text
-                     property with the type \c string and an empty value.
-
-                \li Specify another property, \c fontSize, with the type \c int
-                    and the value \c 10.
-
+                \li In the \uicontrol Id field, enter an ID for the border
+                    image. In this example, we use the ID \e inactiveButton.
+                \li In the \uicontrol Source field, select the image file for
+                    the border image. For example, inactive_button.png.
+                \li In the \uicontrol {Layout} tab, select the
+                    \inlineimage anchor-fill.png
+                    (\uicontrol {Fill to Parent}) button to always make the
+                    image the same size as its parent. This makes the button
+                    component scalable, because the image size is bound to the
+                    component size.
             \endlist
+        \li Select the other border image to edit the values of its properties
+            similarly:
+            \list a
+                \li In the \uicontrol Id field, enter \e activeButton.
+                \li In the \uicontrol Source field, select the image file
+                    for the button when it is clicked. For example,
+                    active_button.png.
+                \li In the \uicontrol {Layout} tab, select the
+                    \inlineimage anchor-fill.png
+                    (\uicontrol {Fill to Parent}) button.
+            \endlist
+        \li Select the text item to specify font size and color in
+            \uicontrol Properties:
+            \list a
+                \li In the \uicontrol Color field, use
+                    the color picker to select the font color, or enter a value
+                    in the field.
+                \li In \uicontrol Font group, \uicontrol Size field, enter the
+                    font size.
+                \li In the \uicontrol {Layout} tab, select
+                    \inlineimage anchor-vertical-center.png
+                    (\uicontrol {Vertical Center}) and
+                    \inlineimage anchor-horizontal-center.png
+                    (\uicontrol {Horizontal Center}) buttons to inherit the
+                    vertical and horizontal centering from the parent.
+                    This ensures that the button label is centered when the
+                    component is resized.
+            \endlist
+    \endlist
 
-        \li Drag and drop two \uicontrol {Border Image} types from the
-            \uicontrol Library to the item in the \uicontrol Navigator.
-
-        \li Drag and drop a \uicontrol Text type to the item in the navigator.
-
-        \li Drag and drop a \uicontrol {Mouse Area} to the item in the
-            navigator.
-
-        \li In the navigator, select a border image to specify settings for it
-            in the \uicontrol Properties view:
-
-        \list a
-
-            \li Select \uicontrol Connections > \uicontrol {Bindings}
-                > \uicontrol Add to hide the image when the mouse button is not
-                pressed down. Specify the \c visible property with the
-                \c !mouseArea source item and \c pressed source property.
-
-                \image qmldesigner-borderimage-bindings.png "Border image bindings"
-
-            \li In the \uicontrol Source field, select the image file for the button,
-                for example button_up.png.
-
-            \li  Click \uicontrol {Layout}, and then click the
-                \inlineimage anchor-fill.png
-                (\uicontrol {Fill to Parent}) button to anchor the border image to the
-                \uicontrol Item.
-
-        \endlist
-
-        \li Select the other border image to specify similar settings for it:
-
-        \list a
-
-            \li In \uicontrol Bindings, specify the \c visible property
-                with the \c mouseArea source item and \c pressed source
-                property to show the image when the mouse button is pressed
-                down.
-
-            \li In the \uicontrol Source field, select the image file for the button
-                when it is clicked, for example button_down.png.
-
-            \li Select \uicontrol {Layout} > \uicontrol {Fill to Parent}
-                button to anchor the border image to the \uicontrol Item.
-
-        \endlist
-
-        \li Select the text to specify font size and color, and text scaling
-            and rendering:
-
-        \list a
-
-            \li In the \uicontrol Color field, use the color picker to select
-                the font color, or enter a value in the field.
-
-            \li In \uicontrol Bindings, create bindings to properties:
-
-                \image qmldesigner-borderimage-bindings-text.png "Text bindings"
-
-                \list
-
-                    \li Set the source property of the \c text property as
-                        \c text and the source item as \c parent.
-
-                    \li Set the source property of the \c font.pixelSize as
-                        \c fontSize and the source item as \c parent.
-
-                    \li Set the source property of \c scale as
-                        \c {if (!mouseArea} and the source item as
-                        \c {pressed) { 1 } else { 0.95 }}.
-
-                \endlist
-
-            \li Click \uicontrol {Layout}, and then click the
-                \inlineimage anchor-vertical-center.png
-                (\uicontrol {Vertical Center}) and
-                \inlineimage anchor-horizontal-center.png
-                (\uicontrol {Horizontal Center}) buttons to inherit the
-                vertical and horizontal centering from the parent.
-
-        \endlist
-
-        \li Select \uicontrol mouseArea in the navigator and then select
-            \uicontrol Connections > \uicontrol Add to set \c item.clicked()
-            as the value of the \c onClicked signal handler.
-
-           \image qmldesigner-borderimage-connections.png "Item connections"
-
-        \li In the \uicontrol {Text Editor}, specify the \c clicked signal for
-            the Item:
-
-            \qml
-            Item {
-                id: item
-                property string text: ""
-                property int fontSize: 10
-
-                signal clicked
-            }
-            \endqml
+    \section1 Using States to Change Component Property Values
 
+    \list 1
+        \li In the \uicontrol States view, select \inlineimage plus.png
+            twice to create two new states.
+            \image qmldesigner-borderimage-states.png "Active and inactive states"
+        \li Select \uicontrol State1.
+        \li Change the state name to \e active.
+        \li Select \inlineimage icons/action-icon.png
+            , and then select \uicontrol {Set when Condition} to determine
+            when the state should be applied.
+        \li In the \uicontrol {Binding Editor}, select the \c mouseArea
+            type and the \c pressed signal to specify that the state is
+            applied when the mouse button is pressed down.
+            \image qmldesigner-borderimage-bindings.png "Active state when condition"
+        \li Select the text item in \uicontrol Navigator to specify that the
+            text size is scaled up when the button is pressed down.
+        \li In \uicontrol Properties, select the \uicontrol Advanced tab, and
+            increase the value of the \uicontrol Scale property.
+        \li Select \e inactiveButton in \uicontrol Navigator to hide
+            it in the \e active state by changing the value of its
+            \uicontrol Visibility property in \uicontrol Properties.
+        \li Select \uicontrol State2.
+        \li Change the state name to \e inactive.
+        \li Set the when condition for the state to \c !mouseArea.pressed to
+            specify that the state is applied when the mouse button is not
+            pressed down.
+            \image qmldesigner-borderimage-bindings1.png "Inactive state when condition"
+            it in the \e inactive state by changing the value of its
+            \uicontrol Visibility property in \uicontrol Properties.
+        \li Press \key {Ctrl+S} to save the button.
+        \li Select the \inlineimage live_preview.png
+            (\uicontrol {Show Live Preview}) button to check how the
+            button behaves when you click it. You can drag the preview
+            window borders to see what happens when you resize the
+            component.
     \endlist
 
-    \note To test the button, add it to a Qt Quick Application or Qt
-    Quick UI project and run the application.
+    To be useful, the button type has to be created in a project.
+    When you work on other QML files in the project to create screens
+    or other components for the UI, the button type appears in the
+    \uicontrol {My QML Components} tab of the \uicontrol Library view.
+    You can drag and drop it to \uicontrol {Form Editor} or
+    \uicontrol Navigator to create button instances and modify the values
+    of their properties to assign them useful IDs, change their appearance,
+    and set the button text for each button instance, for example.
 
-*/
+    For more information about positioning buttons on screens, see
+    \l{Positioning Items in UIs}.
 
+    \image qmldesigner-borderimage.png "Button preview as part of a screen"
+*/