Control: explain diagram and make it a linkable section

Change-Id: I6e0d2349bdc909e61048356d76dc877e33fad5ff
Task-number: QTBUG-55904
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

3 files changed, 414 insertions, 0 deletions

diff --git a/src/imports/controls/doc/images/qtquickcontrols2-control.png b/src/imports/controls/doc/images/qtquickcontrols2-control.png
index 28fcb742..26babc9f 100644
--- a/src/imports/controls/doc/images/qtquickcontrols2-control.png
+++ b/src/imports/controls/doc/images/qtquickcontrols2-control.png
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-control.svg b/src/imports/controls/doc/images/qtquickcontrols2-control.svg
new file mode 100644
index 00000000..b0ffae7c
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-control.svg
@@ -0,0 +1,392 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="679.31317"
+   height="357.84125"
+   viewBox="0 0 679.31314 357.84124"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="qtquickcontrols2-control.svg"
+   inkscape:export-filename="/home/mitch/Dropbox/qtquickcontrols2-control.png"
+   inkscape:export-xdpi="90"
+   inkscape:export-ydpi="90">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutL"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4327"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(0.8,0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleInL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleInL"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4318"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(-0.8,-0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Mstart"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow1Mstart"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4191"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="matrix(0.4,0,0,0.4,4,0)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4212"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6,-0.6)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleInL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleInL-2"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4318-4"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(-0.8,-0.8)" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutL-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4327-1"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(0.8,0.8)" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleInL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleInL-3"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4318-9"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(-0.8,-0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutL-0"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4327-5"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(0.8,0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleInL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleInL-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4318-2"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(-0.8,-0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutL-1"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4327-2"
+         d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1"
+         transform="scale(0.8,0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="2.8"
+     inkscape:cx="370.99138"
+     inkscape:cy="234.56612"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="3742"
+     inkscape:window-height="2124"
+     inkscape:window-x="98"
+     inkscape:window-y="36"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     units="px" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(91.482322,-255.11685)">
+    <rect
+       style="fill:#cccccc;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect4136"
+       width="564.41473"
+       height="248.82799"
+       x="-30.289024"
+       y="321.69858" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138"
+       style="font-style:normal;font-weight:normal;font-size:15.41801071px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(1.1690183,0,0,1.1690183,19.800223,-141.31953)"><flowRegion
+         id="flowRegion4140"><rect
+           id="rect4142"
+           width="129.78784"
+           height="31.668232"
+           x="-34.519978"
+           y="400.22751"
+           style="font-size:15.41801071px;fill:#000000" /></flowRegion><flowPara
+         id="flowPara4144"
+         style="font-size:20.55734825px;fill:#000000">Background</flowPara><flowPara
+         id="flowPara4146" /></flowRoot>    <rect
+       style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:27.60000038;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.58381503"
+       id="rect4148"
+       width="464.22452"
+       height="165.94499"
+       x="18.895706"
+       y="364.74274" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,144.03104,146.23557)"><flowRegion
+         id="flowRegion4140-6"><rect
+           id="rect4142-6"
+           width="334.36047"
+           height="80.812172"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:40px;fill:#000000" /></flowRegion><flowPara
+         id="flowPara4146-6">Content item</flowPara></flowRoot>    <path
+       style="fill:#000000;fill-rule:evenodd;stroke:#000000;stroke-width:1.04880464;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#TriangleInL);marker-end:url(#TriangleOutL)"
+       d="m 27.018805,516.90108 0,-133.62042"
+       id="path4179"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.93839902;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#TriangleInL-2);marker-end:url(#TriangleOutL-9)"
+       d="m 26.776662,538.68728 451.028788,0"
+       id="path4179-7"
+       inkscape:connector-curvature="0" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-2"
+       style="font-style:normal;font-weight:normal;font-size:20px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,10.003309,144.31674)"><flowRegion
+         id="flowRegion4140-6-6"><rect
+           id="rect4142-6-1"
+           width="117.17769"
+           height="101.01524"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:20px;fill:#000000" /></flowRegion><flowPara
+         id="flowPara9732"
+         style="font-size:17.5px;fill:#000000">Available height</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-2-7"
+       style="font-style:normal;font-weight:normal;font-size:17.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,10.811464,253.07573)"><flowRegion
+         id="flowRegion4140-6-6-4"><rect
+           id="rect4142-6-1-4"
+           width="252.53812"
+           height="61.619293"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:17.5px;fill:#000000" /></flowRegion><flowPara
+         style="font-size:17.5px;fill:#000000"
+         id="flowPara10048">Available width</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-1"
+       style="font-style:normal;font-weight:normal;font-size:25px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,210.99354,300.96896)"><flowRegion
+         id="flowRegion4140-6-9"><rect
+           id="rect4142-6-0"
+           width="270.72089"
+           height="68.690361"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:25px;fill:#000000" /></flowRegion><flowPara
+         id="flowPara4146-6-2"
+         style="font-size:17.5px">Width</flowPara></flowRoot>    <path
+       style="fill:#000000;fill-rule:evenodd;stroke:#000000;stroke-width:0.90119678;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#TriangleInL-3);marker-end:url(#TriangleOutL-0)"
+       d="m -26.522148,583.27143 557.292688,0"
+       id="path4179-8"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:#000000;fill-rule:evenodd;stroke:#000000;stroke-width:0.9011969;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#TriangleInL-9);marker-end:url(#TriangleOutL-1)"
+       d="m -43.461661,566.30584 0,-239.7552"
+       id="path4179-9"
+       inkscape:connector-curvature="0" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-1-7"
+       style="font-style:normal;font-weight:normal;font-size:17.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,-112.00353,150.83655)"><flowRegion
+         id="flowRegion4140-6-9-7"><rect
+           id="rect4142-6-0-5"
+           width="270.72089"
+           height="68.690361"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:17.5px;fill:#000000" /></flowRegion><flowPara
+         id="flowPara4146-6-2-9"
+         style="font-size:17.5px;fill:#000000">Height</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-3"
+       style="font-style:normal;font-weight:normal;font-size:60px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,156.72375,-24.786365)"><flowRegion
+         id="flowRegion4140-6-67"><rect
+           id="rect4142-6-5"
+           width="334.36047"
+           height="80.812172"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:60px;fill:#000000" /></flowRegion><flowPara
+         id="flowPara4146-6-3">Control</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-2-7-5"
+       style="font-style:normal;font-weight:normal;font-size:17.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,186.57489,257.45801)"><flowRegion
+         id="flowRegion4140-6-6-4-6"><rect
+           id="rect4142-6-1-4-2"
+           width="252.53812"
+           height="61.619293"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:17.5px;fill:#000000" /></flowRegion><flowPara
+         style="font-size:17.5px;fill:#000000"
+         id="flowPara10048-9">Bottom padding</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-2-7-5-1"
+       style="font-style:normal;font-weight:normal;font-size:17.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,193.9747,48.798368)"><flowRegion
+         id="flowRegion4140-6-6-4-6-2"><rect
+           id="rect4142-6-1-4-2-7"
+           width="252.53812"
+           height="61.619293"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:17.5px;fill:#000000" /></flowRegion><flowPara
+         style="font-size:17.5px;fill:#000000"
+         id="flowPara10048-9-0">Top padding</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-2-7-5-9"
+       style="font-style:normal;font-weight:normal;font-size:17.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,457.80767,148.11921)"><flowRegion
+         id="flowRegion4140-6-6-4-6-3"><rect
+           id="rect4142-6-1-4-2-6"
+           width="81.109558"
+           height="93.762154"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:17.5px;fill:#000000" /></flowRegion><flowPara
+         style="font-size:17.5px;line-height:125%;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#000000"
+         id="flowPara4386">Right padding</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4138-6-2-7-5-9-2"
+       style="font-style:normal;font-weight:normal;font-size:17.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       transform="matrix(0.6007979,0,0,0.6007979,-54.735211,151.06168)"><flowRegion
+         id="flowRegion4140-6-6-4-6-3-5"><rect
+           id="rect4142-6-1-4-2-6-4"
+           width="81.109558"
+           height="93.762154"
+           x="42.426407"
+           y="481.62601"
+           style="font-size:17.5px;fill:#000000" /></flowRegion><flowPara
+         style="font-size:17.02554321px;line-height:125%;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#000000"
+         id="flowPara4386-0">Left padding</flowPara></flowRoot>  </g>
+</svg>
diff --git a/src/quicktemplates2/qquickcontrol.cpp b/src/quicktemplates2/qquickcontrol.cpp
index 4d8609f7..e294055c 100644
--- a/src/quicktemplates2/qquickcontrol.cpp
+++ b/src/quicktemplates2/qquickcontrol.cpp
@@ -70,8 +70,26 @@ QT_BEGIN_NAMESPACE
     events from the window system, and paints a representation of itself on
     the screen.
 
+    \section1 Control Layout
+
+    The following diagram illustrates the layout of a typical control:
+
     \image qtquickcontrols2-control.png
 
+    The \l {Item::}{implicitWidth} and \l {Item::}{implicitHeight} of a control
+    are typically based on the implicit sizes of the background and the content
+    item plus any \l {Control::}{padding}. These properties determine how large
+    the control will be when no explicit \l {Item::}{width} or
+    \l {Item::}{height} is specified.
+
+    The \l {Control::}{background} item fills the entire width and height of the
+    control, unless an explicit size has been given for it.
+
+    The geometry of the \l {Control::}{contentItem} is determined by the
+    padding.
+
+    \section1 Event Handling
+
     All controls, except non-interactive indicators, do not let clicks and
     touches through to items below them. For example, if \l Pane is used as the
     \l {ApplicationWindow::}{header} or \l {ApplicationWindow::}{footer} of
@@ -946,6 +964,8 @@ void QQuickControl::setWheelEnabled(bool enabled)
     \note If the background item has no explicit size specified, it automatically
           follows the control's size. In most cases, there is no need to specify
           width or height for a background item.
+
+    \sa {Control Layout}
 */
 QQuickItem *QQuickControl::background() const
 {
@@ -977,6 +997,8 @@ void QQuickControl::setBackground(QQuickItem *background)
     This property holds the visual content item.
 
     \note The content item is automatically resized inside the \l padding of the control.
+
+    \sa {Control Layout}
 */
 QQuickItem *QQuickControl::contentItem() const
 {