[libcalamaresui] Introduce search method for QML UI modules

- add a sample config and documentation in dummyqml/

src/libcalamaresui/viewpages/QmlViewStep.cpp

@@ -20,6 +20,8 @@
 
 #include "utils/Dirs.h"
 #include "utils/Logger.h"
+#include "utils/NamedEnum.h"
+#include "utils/Variant.h"
 #include "widgets/WaitingWidget.h"
 
 #include <QQmlComponent>
@@ -29,6 +31,19 @@
 #include <QVBoxLayout>
 #include <QWidget>
 
+static const NamedEnumTable< Calamares::QmlViewStep::QmlSearch >&
+searchNames()
+{
+    using QmlSearch = Calamares::QmlViewStep::QmlSearch;
+    static NamedEnumTable< Calamares::QmlViewStep::QmlSearch > names{
+        { QStringLiteral( "both" ), QmlSearch::Both },
+        { QStringLiteral( "qrc" ), QmlSearch::QrcOnly },
+        { QStringLiteral( "branding" ), QmlSearch::BrandingOnly }
+    };
+
+    return names;
+}
+
 namespace Calamares
 {
 
@@ -165,3 +180,13 @@ Calamares::QmlViewStep::showQml()
         cDebug() << "showQml() called twice";
     }
 }
+
+void Calamares::QmlViewStep::setConfigurationMap(const QVariantMap& configurationMap)
+{
+    bool ok = false;
+    m_searchMethod = searchNames().find( CalamaresUtils::getString( configurationMap, "search" ), ok );
+    if (!ok)
+    {
+        cDebug() << "Bad QML search mode.";
+    }
+}

src/libcalamaresui/viewpages/QmlViewStep.h

@@ -40,6 +40,20 @@ class QmlViewStep : public Calamares::ViewStep
     Q_OBJECT
 
 public:
+    enum class QmlSearch
+    {
+        QrcOnly,
+        BrandingOnly,
+        Both
+    };
+
+    /** @brief Creates a QML view step
+     *
+     * The name should not have an extension or schema or anything;
+     * just the plain name, which will be searched as "/<name>.qml" in
+     * QRC files, or "<name>.qml" in suitable branding paths.
+     * The search behavior depends on a QmlSearch value.
+     */
     QmlViewStep( const QString& name, QObject* parent = nullptr );
     virtual ~QmlViewStep() override;
 
@@ -56,8 +70,12 @@ public:
     virtual void onActivate() override;
     virtual void onLeave() override;
 
+    /// @brief QML widgets don't produce jobs by default
     virtual JobList jobs() const override;
 
+    /// @brief Configure search paths; subclasses should call this as well
+    virtual void setConfigurationMap( const QVariantMap& configurationMap ) override;
+
 private Q_SLOTS:
     void loadComplete();
 
@@ -65,6 +83,9 @@ private:
     /// @brief Swap out the spinner for the QQuickWidget
     void showQml();
 
+    /// @brief Controls where m_name is searched
+    QmlSearch m_searchMethod;
+
     QString m_name;
     QString m_qmlFileName;
 

src/modules/dummyqml/dummyqml.conf

@@ -0,0 +1,19 @@
+# The dummy QML module just displays a QML page. It doesn't
+# have much in the way of own configuration, only where
+# the QML file is searched.
+#
+# QML modules can search for the QML inside the Qt resources
+# (QRC) which are compiled into the module, or in the branding
+# setup for Calamares, (or both of them, with branding taking
+# precedence). This allows the module to ship a default UI and
+# branding to optionally introduce a replacement file.
+#
+# Generally, leave the search method set to "both" because if
+# you don't want to brand the UI, just don't ship a branding
+# QML file for it.
+#
+# To support instanced QML modules, searches in the branding
+# directory look for the full module@instanceid name as well.
+---
+search: both
+