Merge remote-tracking branch 'origin/5.15' into dev

Change-Id: Ie6039c9ad6c5b0d5077383f0a797be320cd34739

5 files changed, 135 insertions, 33 deletions

diff --git a/src/imports/controls/doc/qtquickcontrols.qdocconf b/src/imports/controls/doc/qtquickcontrols.qdocconf
index f6798f1f..d52aceb8 100644
--- a/src/imports/controls/doc/qtquickcontrols.qdocconf
+++ b/src/imports/controls/doc/qtquickcontrols.qdocconf
@@ -33,7 +33,7 @@ qhp.QtQuickControls.subprojects.examples.title = Examples
 qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples
 qhp.QtQuickControls.subprojects.examples.selectors = fake:example
 
-depends = qtcore qtgui qtdoc qtqml qtquick qtquickdialogs qtquickcontrols1 qtquickextras qmake qtsql qtwidgets qtlabscalendar qtlabsplatform qtgraphicaleffects
+depends = qtcore qtgui qtdoc qtqml qtqmlmodels qtquick qtquickdialogs qtquickcontrols1 qtquickextras qmake qtsql qtwidgets qtlabscalendar qtlabsplatform qtgraphicaleffects
 
 # Specify the install path under QT_INSTALL_EXAMPLES
 # Note: paths passed to \example command must contain the parent directory, e.g.
diff --git a/src/imports/controls/doc/src/includes/customize-button-background.qdocinc b/src/imports/controls/doc/src/includes/customize-button-background.qdocinc
new file mode 100644
index 00000000..59df7d8e
--- /dev/null
+++ b/src/imports/controls/doc/src/includes/customize-button-background.qdocinc
@@ -0,0 +1,25 @@
+//! [file]
+\qml \QtMinorVersion
+import QtQuick 2.\1
+import QtQuick.Controls 2.\1
+
+ApplicationWindow {
+    width: 400
+    height: 400
+    visible: true
+
+    Button {
+        id: button
+        text: "A Special Button"
+        background: Rectangle {
+            implicitWidth: 100
+            implicitHeight: 40
+            color: button.down ? "#d6d6d6" : "#f6f6f6"
+            border.color: "#26282a"
+            border.width: 1
+            radius: 4
+        }
+    }
+}
+\endqml
+//! [file]
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
index cd06a456..5901663a 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -48,29 +48,7 @@
     can override the \l {Control::}{background} item and set the radius
     property of Rectangle:
 
-    \qml \QtMinorVersion
-    import QtQuick 2.\1
-    import QtQuick.Controls 2.\1
-
-    ApplicationWindow {
-        width: 400
-        height: 400
-        visible: true
-
-        Button {
-            id: button
-            text: "A Special Button"
-            background: Rectangle {
-                implicitWidth: 100
-                implicitHeight: 40
-                color: button.down ? "#d6d6d6" : "#f6f6f6"
-                border.color: "#26282a"
-                border.width: 1
-                radius: 4
-            }
-        }
-    }
-    \endqml
+    \include customize-button-background.qdocinc file
 
     The second way to create the button is good if you plan to use your rounded
     button in several places. It involves moving the code into its own QML file
@@ -166,7 +144,8 @@
 
     By default, the styling system uses the Default style as a fallback for
     controls that aren't implemented. To customize or extend any other built-in
-    style, it is possible to specify a different fallback style using \l QQuickStyle.
+    style, it is possible to specify a different fallback style using
+    \l[QtQuickControls2]{QQuickStyle}.
 
     What this means is that you can implement as many controls as you like for
     your custom style, and place them almost anywhere. It also allows users to
@@ -175,7 +154,7 @@
     \section3 Previewing Custom Styles in Qt Quick Designer
 
     Using the approach above, it is possible to preview a custom style
-    in \l {Using Qt Quick Designer}{Qt Quick Designer}. In order to do so,
+    in Qt Quick Designer. In order to do so,
     ensure that the project has a
     \l {Qt Quick Controls Configuration File}{qtquickcontrols2.conf} file,
     and that the following entry exists:
@@ -213,6 +192,102 @@
         files.
     \endlist
 
+    \section3 Considerations for custom styles
+
+    When implementing your own style and customizing controls, there are some
+    points to keep in mind to ensure that your application is as performant as
+    possible.
+
+    \section4 Avoid assigning an id to styles' implementations of item delegates
+
+    As explained in \l {Definition of a Style}, when you implement your
+    own style for a control, you start off with the relevant template for
+    that control. For example, a style's \c Button.qml will be structured
+    similarly to this:
+
+    \qml
+    T.Button {
+        // ...
+
+        background: Rectangle {
+            // ...
+        }
+
+        contentItem: Text {
+            // ...
+        }
+
+        // ...
+    }
+    \endqml
+
+    When you use a Button in your application, the \c background and
+    \c contentItem items will be created and parented to the root \c Button
+    item:
+
+    \qml
+    // Creates the Button root item, the Rectangle background,
+    // and the Text contentItem.
+    Button {
+        text: qsTr("Confirm")
+    }
+    \endqml
+
+    Suppose you then needed to do a one-off customization of the Button (as
+    explained in \l {Customizing a Control}):
+
+    \include customize-button-background.qdocinc file
+
+    In QML, this would normally result in both the default \c background
+    implementation and the one-off, custom \c background items being created.
+    Qt Quick Controls uses a technique that avoids creating both items, and
+    instead only creates the custom \c background, greatly improving the
+    creation performance of controls.
+
+    This technique relies on the absence of an \l {The id Attribute}{id} in the
+    style's implementation of that item. If an id is assigned, the technique
+    cannot work, and both items will be created. For example, it can be
+    tempting to assign an id to the \c background or \c contentItem so that
+    other objects within the file can refer to those items:
+
+    \qml
+    T.Button {
+        // ...
+
+        background: Rectangle {
+            id: backgroundRect
+            // ...
+        }
+
+        contentItem: Text {
+            // Use backgroundRect in some way...
+        }
+
+        // ...
+    }
+    \endqml
+
+    With this code, every time a Button instance with a customized background
+    is created, both backgrounds will be created, resulting in sub-optimal
+    creation performance.
+
+    Prior to Qt 5.15, the old, unused background would be deleted to release
+    the resources associated with it. However, as the control does not own the
+    items, it should not delete them. As of Qt 5.15, old items are no longer
+    deleted, and so the \c backgroundRect item will live longer than it needs
+    to—typically until the application exits. Although the old item will be
+    hidden, visually unparented from the control, and removed from the
+    accessibility tree, it is important to keep the creation time and memory
+    usage of these unused items in mind when assigning an id in this context.
+
+    \section4 Avoid imperative assignments of custom items
+
+    The technique mentioned in the section above only works when an item is
+    \l {Prefer Declarative Bindings Over Imperative Assignments}{declaratively}
+    assigned for the first time, and so imperative assignments will result in
+    orphaned items. Always use declarative bindings to assign custom items
+    when possible.
+
     \section3 Attached properties
 
     It is common for a style to have certain properties or attributes that
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc
index 6e15762d..ac2e9cc1 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc
@@ -2478,7 +2478,7 @@
 
     The Imagine style supports palette customization via the \l {Control::}{palette}
     property and the \l {Palette Configuration}{qtquickcontrols2.conf} file.
-    As with other styles, the exact \l {palette QML Basic Type}{palette roles}
+    As with other styles, the exact \l[QML]{palette}{palette roles}
     that the Imagine style uses are style-dependent. However, as most of the visual
     appearance of controls (for example: backgrounds) are managed through image assets,
     only the roles that are typically used for text will have an effect.
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc
index 75e59f42..ddf41771 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc
@@ -70,15 +70,15 @@
     \section1 Using Styles in Qt Quick Controls
 
     In order to run an application with a specific style, either configure the
-    style using \l QQuickStyle in C++, pass a command line argument, or set an
+    style using \l[CPP]{QQuickStyle} in C++, pass a command line argument, or set an
     environment variable. Alternatively, the preferred style and style-specific
     attributes can be specified in a configuration file.
 
     The priority of these approaches follows the order they are listed below,
-    from highest to lowest. That is, using QQuickStyle to set the style will
+    from highest to lowest. That is, using \c QQuickStyle to set the style will
     always take priority over using the command line argument, for example.
 
-    \warning When resolving a given style name to an absolute path, QQuickStyle
+    \warning When resolving a given style name to an absolute path, \c QQuickStyle
     may search the root resource directory (\c {:}). Consequently, make sure
     that your resource directories are named differently than the names of the
     styles that your application supports. Otherwise, the styles may not load.
@@ -87,14 +87,16 @@
 
     \section2 Using QQuickStyle in C++
 
-    \l QQuickStyle provides C++ API for configuring a specific style. The following
-    example runs a Qt Quick Controls application with the Material style:
+    \l[CPP]{QQuickStyle} provides C++ API for configuring a specific
+    style. The following example runs a Qt Quick Controls application
+    with the Material style:
 
     \code
     QQuickStyle::setStyle("Material");
     \endcode
 
-    See the detailed description of \l QQuickStyle for more details.
+    See the detailed description of \l[CPP]{QQuickStyle} for more
+    details.
 
     \section2 Command line argument