Use qmlRegisterModuleImport() to register styles

This patch completes the cumulative work done in previous patches.

- Uses qmlRegisterModuleImport() to register styles. This has some
  added requirements:
  - Each style must now be a QML module -- that is, it must have a
    qmldir file.
  - As a result of the above, the module must be available within the
    QML import path in order to be found.
  - The various forms of accepted style names have been reduced down to
    one ("Material", "MyStyle", etc). See below for an explanation of
    why.
  - The following API in QQuickStyle is removed:
    addStylePath(), availableStyles(), path(), stylePathList(). These
    no longer make sense now that we reuse the existing QML import
    system.
- Adds the tst_qquickstyleselector auto test back as "styleimports".

qmlRegisterModuleImport() vs resolvedUrl()

    Previously we would use QQuickStyleSelector to select individual
    QML files based on which style was set. We'd do this once when
    QtQuick.Controls was first imported.

    With Qt 6, and the requirement that each style be a proper QML
    module, qmlRegisterModuleImport() was introduced. This allows us
    to "link" one import with another. For an example of what this
    looks like in practice, suppose the style was set to "MyStyle",
    and the fallback to "Material". The "QtQuick.Controls" import
    will be linked to "MyStyle", "MyStyle" to
    "QtQuick.Controls.Material", and as a final fallback (for controls
    like Action which only the Default style implements),
    "QtQuick.Controls.Material" to "QtQuick.Controls.Default".
    This is the same behavior as in Qt 5 (see qquickstyleselector.cpp):

    // 1) requested style (e.g. "MyStyle", included in d->selectors)
    // 2) fallback style (e.g. "Material", included in d->selectors)
    // 3) default style (empty selector, not in d->selectors)

    This is a necessary step to enable compilation of QML to C++.

Reducing the set of accepted style names

    The problem

    In QtQuickControls2Plugin() we need to call
    QQuickStylePrivate::init(baseUrl()) in order to detect if the style
    is a custom style in QQuickStyleSpec::resolve() (by checking if the
    style path starts with the base URL). In Qt 5, init() is called in
    QtQuickControls2Plugin::registerTypes(), but in Qt 6 that's too
    late, because we need to call qmlRegisterModuleImport() in the
    constructor. qmlRegisterModuleImport() itself requires the style to
    have already been set in order to create the correct import URI
    ("QtQuick.Controls.X" for built-in styles, "MyCustomStyle" for
    custom styles).

    The solution

    By reducing the valid forms for style names down to one:

    ./myapp -style MyStyle

    we solve the problem of needing baseUrl() to determine if the
    style is a custom style or not, but needing to call it too early
    (since we now call qmlRegisterModuleImport() in
    QtQuickControls2Plugin(), which itself requires the style to have
    already been set). baseUrl() can't have been set before the
    constructor is finished.

    All of the various forms for _setting_ a style are still valid;
    environment variables, qtquickcontrols2.conf, etc.

[ChangeLog][Important Behavior Changes] Custom styles must now have
a qmldir that lists the files that the style implements. For example,
for a style that only implements Button:
---
module MyStyle
Button 1.0 Button.qml
---
In addition, there is now only one valid, case-sensitive form for style
names: "Material", "MyStyle", etc.
These changes are done to help enable the compilation of QML code to
C++, as well as improve tooling capabilities.

[ChangeLog][Important Behavior Changes] The following API was removed:
- QQuickStyle::addStylePath()
- QQuickStyle::availableStyles()
- QQuickStyle::path()
- QQuickStyle::stylePathList()
- QT_QUICK_CONTROLS_STYLE_PATH
This API is no longer necessary and/or able to be provided now that
styles are treated as regular QML modules.

Task-number: QTBUG-82922
Change-Id: I3b281131903c7c3c1cf0616eb7486a872dccd730
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

1 files changed, 31 insertions, 13 deletions

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
index 6ab649d0..58138a07 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -112,7 +112,7 @@
     \section2 Definition of a Style
 
     In Qt Quick Controls, a style is essentially an interchangeable set of
-    QML files within a single directory. There are three requirements for a style
+    QML files within a single directory. There are four requirements for a style
     to be \l {Using Styles in Qt Quick Controls}{usable}:
 
     \list
@@ -125,21 +125,37 @@
         If we instead used the corresponding type from the \l {Qt Quick Controls}
         {QtQuick.Controls} import as we did in the previous section, it would not work:
         the control we were defining would try to derive from itself.
-    \li The files must be in a directory in the filesystem or in the
-        \l {The Qt Resource System}{resource system}.
+    \li A \l {Module Definition qmldir Files}{qmldir} file must exist alongside
+        the QML file(s). Below is an example of a simple \c qmldir file for a style that
+        provides a button:
 
-        For example, these are all valid paths to a style:
+        \badcode
+        module MyStyle
+        Button 2.15 Button.qml
+        \endcode
+
+        The directory structure for such a style looks like this:
+
+        \badcode
+        MyStyle
+        ├─── Button.qml
+        └─── qmldir
+        \endcode
+    \li The files must be in a directory that is findable via the \l {QML Import Path}.
+
+        For example, if the path to \e MyStyle directory mentioned above was
+        \c /home/user/MyApp/MyStyle, then \c /home/user/MyApp must be added to
+        the QML import path.
+
+        To \l {Using Styles in Qt Quick Controls}{use} \e MyStyle in \e MyApp,
+        refer to it by name:
 
         \list
-        \li \c {./myapp -style /home/absolute/path/to/my/style}
-        \li \c {./myapp -style :/mystyle}
-        \li \c {./myapp -style relative/path/to/my/style}
-        \li \c {./myapp -style MyStyle}
+        \li \c {./MyApp -style MyStyle}
         \endlist
 
-        The third and fourth paths will be looked up within the QML engine's import path
-        list. This is the same as what happens when you pass \c Material as the style,
-        for example.
+        The style name must match the casing of the style directory; passing
+        \e mystyle or \e MYSTYLE is not supported.
     \endlist
 
     By default, the styling system uses the Default style as a fallback for
@@ -302,7 +318,7 @@
     style will illustrate the elevation with a drop shadow; the higher the
     elevation, the larger the shadow.
 
-    The first step is to \l {Qt Creator: Creating Qt Quick Projects}{create a new Qt Quick
+    The first step is to \l {Creating Qt Quick Projects}{create a new Qt Quick
     Controls 2 application} in Qt Creator. After that, we
     \l {Qt Creator: Creating C++ Classes}{add a C++ type} that stores the elevation. Since
     the type will be used for every control supported by our style, and because
@@ -390,6 +406,8 @@
         qmlRegisterUncreatableType<MyStyle>("MyStyle", 1, 0, "MyStyle", "MyStyle is an attached property");
 
         QQmlApplicationEngine engine;
+        // Make the directory containing our style known to the QML engine.
+        engine.addImportPath(":/");
         engine.load(QUrl(QLatin1String("qrc:/main.qml")));
 
         return app.exec();
@@ -465,7 +483,7 @@
     One button has no elevation, and the other has an elevation of \c 10.
 
     With that in place, we can run our example. To tell the application to
-    use our new style, we pass \c {-style :/mystyle} as an application
+    use our new style, we pass \c {-style MyStyle} as an application
     argument, but there are \l {Using Styles in Qt Quick Controls}{many
     ways} to specify the style to use.