StyleKit: rename and document AbstractStylableControls.getControlStyle()

AbstractStylableControls.getControl() is missing documentation. And
the name "getControl" can also be confusing, since it's not returning
a Qt Quick Control, but a StyleKit ControlStyle.

This patch will therefore rename getControl() to getControlStyle(),
and document it.

Change-Id: Ib4169f2c665776a9effdd41df28e63d67df02d58
Reviewed-by: Doris Verria <doris.verria@qt.io>
(cherry picked from commit 673beff16f331359f2afa5b2b4fe1297a597b060)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

6 files changed, 63 insertions, 11 deletions

diff --git a/examples/stylekit/stylekitcontrols/Main.qml b/examples/stylekit/stylekitcontrols/Main.qml
index 30af526e73..802619e1a0 100644
--- a/examples/stylekit/stylekitcontrols/Main.qml
+++ b/examples/stylekit/stylekitcontrols/Main.qml
@@ -442,7 +442,7 @@ ApplicationWindow {
             onTapped: {
                 // Change the background color of all controls whose
                 // controlType matches fancyButton.type.
-                let fancyButtons = StyleKit.style.theme.getControl(fancyButton.type)
+                let fancyButtons = StyleKit.style.theme.getControlStyle(fancyButton.type)
                 if (fancyButtons) // Only the Haze style defines a fancyButton
                     fancyButtons.background.color = "yellowgreen"
             }
diff --git a/src/labs/stylekit/doc/snippets/ControlsSnippets.qml b/src/labs/stylekit/doc/snippets/ControlsSnippets.qml
index 18578d316d..12e79f89ec 100644
--- a/src/labs/stylekit/doc/snippets/ControlsSnippets.qml
+++ b/src/labs/stylekit/doc/snippets/ControlsSnippets.qml
@@ -902,7 +902,30 @@ ApplicationWindow {
             label.text.color: "white"
         }
         //! [theme]
+
+    }
+
+    //! [getControlStyle]
+    Style {
+        id: myStyle
+        property int customButtonType: 0
+
+        CustomControl {
+            controlType: myStyle.customButtonType
+            background.color: "green"
+        }
+    }
+    //! [getControlStyle]
+
+    //! [getControlStyle-function]
+    function changeButtonColor() {
+        let customControlStyle = myStyle.getControlStyle(style.customButtonType)
+        customControlStyle.background.color = "yellowgreen"
+
+        // You can also access the style definition in the theme, if it has one
+        // myStyle.theme.getControlStyle(StyleReader.Button).padding = 10
     }
+    //! [getControlStyle-function]
 
     // The rest of the file is not a part of the docs. It just implements a small
     // UI to allow testing the style from the command line using the 'qml' app.
diff --git a/src/labs/stylekit/qqstylekitcontrols.cpp b/src/labs/stylekit/qqstylekitcontrols.cpp
index 51cc5d939a..97344012a6 100644
--- a/src/labs/stylekit/qqstylekitcontrols.cpp
+++ b/src/labs/stylekit/qqstylekitcontrols.cpp
@@ -606,13 +606,42 @@ const QList<QObject *> QQStyleKitControls::children() const
     return m_data;
 }
 
+/*!
+    \qmlmethod ControlStyle AbstractStylableControls::getControlStyle(controlType)
+
+    Returns the \l ControlStyle for the given \a controlType, or \c null, if
+    no \l ControlStyle for the type has been defined.
+
+    \a controlType can be one of the built-in types documented by
+    \l {StyleReader::controlType}{StyleReader.controlType}, or the
+    \l {CustomControl::controlType}{controlType} of a \l CustomControl.
+
+    This function can be used to, for example, read or write a property on
+    a \l CustomControl's style at runtime:
+
+    \snippet ControlsSnippets.qml getControlStyle
+
+    \snippet ControlsSnippets.qml getControlStyle-function
+
+    If \a controlType is a built-in type (such as \c {StyleReader.Button}),
+    using for example \c {myStyle.button} or \c {myStyle.getControlStyle(StyleReader.Button)}
+    to get the \l ControlStyle is \e almost equivalent.
+    The difference is that the former will lazily create a \l ControlStyle if
+    it's not yet defined, while the latter will instead return \c null.
+    This means that for example \c {myStyle.button.padding = 10} is always
+    safe, while \c {myStyle.getControlStyle(StyleReader.Button).padding = 10} will
+    fail if \c {myStyle.button} has not been defined in the \l Style.
+
+    \sa CustomControl, StyleReader
+*/
+
 /* Lazy-create the controls that the style is actually using, when accessed
  * from the style/application (e.g from Style or Theme). We don't lazy
  * create any controls while resolving style properties, as undefined controls would
  * anyway not contain any property overrides. The properties have setters too, to
  * allow the style/application to share custom ControlStyle the classical
  * way, e.g button: ControlStyle { id: button }. */
-QQStyleKitControl* QQStyleKitControls::getControl(QQStyleKitExtendableControlType controlType) const
+QQStyleKitControl* QQStyleKitControls::getControlStyle(QQStyleKitExtendableControlType controlType) const
 {
     return m_controls.value(controlType, nullptr);
 }
diff --git a/src/labs/stylekit/qqstylekitcontrols_p.h b/src/labs/stylekit/qqstylekitcontrols_p.h
index 3dd522c035..b4b727d546 100644
--- a/src/labs/stylekit/qqstylekitcontrols_p.h
+++ b/src/labs/stylekit/qqstylekitcontrols_p.h
@@ -139,7 +139,7 @@ public:
 
 #undef IMPLEMENT_ACCESSORS
 
-    Q_INVOKABLE QQStyleKitControl *getControl(QQStyleKitExtendableControlType controlType) const;
+    Q_INVOKABLE QQStyleKitControl *getControlStyle(QQStyleKitExtendableControlType controlType) const;
 
     QQmlListProperty<QObject> data();
     const QList<QObject *> children() const;
diff --git a/src/labs/stylekit/qqstylekitcustomcontrol.cpp b/src/labs/stylekit/qqstylekitcustomcontrol.cpp
index c0e710a6c0..0b905d9040 100644
--- a/src/labs/stylekit/qqstylekitcustomcontrol.cpp
+++ b/src/labs/stylekit/qqstylekitcustomcontrol.cpp
@@ -42,7 +42,7 @@ QT_BEGIN_NAMESPACE
 
     \labs
 
-    \sa StyleReader, ControlStyle, Style
+    \sa StyleReader, ControlStyle, Style, AbstractStylableControls::getControlStyle()
 */
 
 /*!
@@ -54,7 +54,7 @@ QT_BEGIN_NAMESPACE
 
     Custom control types must be in the range \c 0 to \c 100000.
 
-    \sa {StyleReader::controlType}{StyleReader.controlType}
+    \sa {StyleReader::controlType}{StyleReader.controlType}, AbstractStylableControls::getControlStyle()
 */
 
 using namespace Qt::StringLiterals;
diff --git a/src/labs/stylekit/qqstylekitpropertyresolver.cpp b/src/labs/stylekit/qqstylekitpropertyresolver.cpp
index 5aa307e5e4..66e6abfd0f 100644
--- a/src/labs/stylekit/qqstylekitpropertyresolver.cpp
+++ b/src/labs/stylekit/qqstylekitpropertyresolver.cpp
@@ -195,11 +195,11 @@ void QQStyleKitPropertyResolver::addTypeVariationsToReader(
                  continue;
             }
 
-            if (variation->getControl(styleReaderType)) {
+            if (variation->getControlStyle(styleReaderType)) {
                 addVariationToReader(styleReader, styleOrTheme, variation);
             } else {
                 for (int type : styleReaderBaseType) {
-                    if (variation->getControl(type))
+                    if (variation->getControlStyle(type))
                         addVariationToReader(styleReader, styleOrTheme, variation);
                 }
             }
@@ -230,11 +230,11 @@ void QQStyleKitPropertyResolver::addInstanceVariationsToReader(
                  * a name in the attached variation list. Check if the found variation contains the
                  * type, or the subtypes, of the style reader. If not, it doesn't affect it and can
                  * therefore be skipped. */
-                if (variation->getControl(styleReaderType)) {
+                if (variation->getControlStyle(styleReaderType)) {
                     addVariationToReader(styleReader, styleOrTheme, variation);
                 } else {
                     for (int baseType : styleReaderBaseTypes) {
-                        if (variation->getControl(baseType))
+                        if (variation->getControlStyle(baseType))
                             addVariationToReader(styleReader, styleOrTheme, variation);
                     }
                 }
@@ -454,14 +454,14 @@ QVariant QQStyleKitPropertyResolver::readPropertyInRelevantControls(
         return {};
     }
 
-    if (const QQStyleKitControl *control = controls->getControl(exactType)) {
+    if (const QQStyleKitControl *control = controls->getControlStyle(exactType)) {
         const QVariant value = readPropertyInControl(ids, control);
         if (value.isValid())
             return value;
     }
 
     for (const int type : baseTypes) {
-        if (const QQStyleKitControl *control = controls->getControl(type)) {
+        if (const QQStyleKitControl *control = controls->getControlStyle(type)) {
             const QVariant value = readPropertyInControl(ids, control);
             if (value.isValid())
                 return value;