Introduce required properties to QML

[ChangeLog][QtQml]
"required" is now a (contextual) keyword in QML, and users can
mark properties with it to specify that those properties must be set
when the component gets instantiated.
This can be done either declaratively via standard property
bindings from QML, or imperatively by using the functions to set initial
properties (QQmlCompoent::setInitalProperties and related functions in
C++, Qt.createObject, Loader.setSource,... in QML/JS).
Logic has been added to QQmlComponent::create and the various QQmlIncubator
classes to verify that the required properties were set. If properties
marked as required are not set, a warning will be printed at runtime,
and the component will not be created.

Change-Id: I8e38227fc8f173b053b689c1597dc7fd40e835e7
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>

1 files changed, 77 insertions, 24 deletions

diff --git a/tests/auto/qml/qqmlcomponent/tst_qqmlcomponent.cpp b/tests/auto/qml/qqmlcomponent/tst_qqmlcomponent.cpp
index 79ec507388..b6cc7fd866 100644
--- a/tests/auto/qml/qqmlcomponent/tst_qqmlcomponent.cpp
+++ b/tests/auto/qml/qqmlcomponent/tst_qqmlcomponent.cpp
@@ -121,6 +121,9 @@ private slots:
     void relativeUrl_data();
     void relativeUrl();
     void setDataNoEngineNoSegfault();
+    void testRequiredProperties_data();
+    void testRequiredProperties();
+    void testRequiredPropertiesFromQml();
     void testSetInitialProperties();
 
 private:
@@ -668,35 +671,80 @@ void tst_qqmlcomponent::setDataNoEngineNoSegfault()
     QVERIFY(!c);
 }
 
-void tst_qqmlcomponent::testSetInitialProperties()
+void tst_qqmlcomponent::testRequiredProperties_data()
+{
+    QTest::addColumn<QUrl>("testFile");
+    QTest::addColumn<bool>("shouldSucceed");
+    QTest::addColumn<QString>("errorMsg");
+
+    QTest::addRow("requiredSetViaChainedAlias") << testFileUrl("requiredSetViaChainedAlias.qml") << true << "";
+    QTest::addRow("requiredNotSet") << testFileUrl("requiredNotSet.qml") << false << "Required property i was not initialized";
+    QTest::addRow("requiredSetInSameFile") << testFileUrl("requiredSetInSameFile.qml") << true << "";
+    QTest::addRow("requiredSetViaAlias1") << testFileUrl("requiredSetViaAliasBeforeSameFile.qml") << true << "";
+    QTest::addRow("requiredSetViaAlias2") << testFileUrl("requiredSetViaAliasAfterSameFile.qml") << true << "";
+    QTest::addRow("requiredSetViaAlias3") << testFileUrl("requiredSetViaAliasParentFile.qml") << true << "";
+    QTest::addRow("shadowing") << testFileUrl("shadowing.qml") << false <<  "Required property i was not initialized";
+    QTest::addRow("setLater") << testFileUrl("requiredSetLater.qml") << true << "";
+    QTest::addRow("setViaAliasToSubcomponent") << testFileUrl("setViaAliasToSubcomponent.qml") << true << "";
+    QTest::addRow("aliasToSubcomponentNotSet") << testFileUrl("aliasToSubcomponentNotSet.qml") << false << "It can be set via the alias property i_alias";
+}
+
+
+void tst_qqmlcomponent::testRequiredProperties()
+{
+    QQmlEngine eng;
+    using QScopedObjPointer = QScopedPointer<QObject>;
+    QFETCH(QUrl, testFile);
+    QFETCH(bool, shouldSucceed);
+    QQmlComponent comp(&eng);
+    comp.loadUrl(testFile);
+    QScopedObjPointer obj {comp.create()};
+    if (shouldSucceed)
+        QVERIFY(obj);
+    else {
+        QVERIFY(!obj);
+        QFETCH(QString, errorMsg);
+        QVERIFY(comp.errorString().contains(errorMsg));
+    }
+}
+
+void tst_qqmlcomponent::testRequiredPropertiesFromQml()
 {
     QQmlEngine eng;
     {
-        // JSON based initialization
         QQmlComponent comp(&eng);
-        comp.loadUrl(testFileUrl("allJSONTypes.qml"));
-        QScopedPointer<QObject> obj { comp.beginCreate(eng.rootContext()) };
+        comp.loadUrl(testFileUrl("createdFromQml.qml"));
+        QScopedPointer<QObject> obj { comp.create() };
         QVERIFY(obj);
-        comp.setInitialProperties(obj.get(), QVariantMap {
-                {QLatin1String("i"), 42},
-                {QLatin1String("b"), true},
-                {QLatin1String("d"), 3.1416},
-                {QLatin1String("s"), QLatin1String("hello world")},
-                {QLatin1String("nothing"), QVariant::fromValue(nullptr)}
-        });
-        comp.completeCreate();
-        if (!comp.errors().empty())
-            qDebug() << comp.errorString() << comp.errors();
-        QVERIFY(comp.errors().empty());
-        QCOMPARE(obj->property("i"), 42);
-        QCOMPARE(obj->property("b"), true);
-        QCOMPARE(obj->property("d"), 3.1416);
-        QCOMPARE(obj->property("s"), QLatin1String("hello world"));
-        QCOMPARE(obj->property("nothing"), QVariant::fromValue(nullptr));
+        auto root = qvariant_cast<QQuickItem*>(obj->property("it"));
+        QVERIFY(root);
+        QCOMPARE(root->property("i").toInt(), 42);
     }
     {
-        //  QVariant
+        QTest::ignoreMessage(QtMsgType::QtWarningMsg, QRegularExpression(".*requiredNotSet.qml:4:5: Required property i was not initialized"));
         QQmlComponent comp(&eng);
+        comp.loadUrl(testFileUrl("createdFromQmlFail.qml"));
+        QScopedPointer<QObject> obj { comp.create() };
+        QVERIFY(obj);
+        QCOMPARE(qvariant_cast<QQuickItem *>(obj->property("it")), nullptr);
+    }
+}
+
+struct ComponentWithPublicSetInitial : QQmlComponent
+{
+    using QQmlComponent::QQmlComponent;
+    void setInitialProperties(QObject *o, QVariantMap map)
+    {
+        QQmlComponent::setInitialProperties(o, map);
+    }
+};
+
+void tst_qqmlcomponent::testSetInitialProperties()
+{
+    QQmlEngine eng;
+    {
+        //  QVariant
+        ComponentWithPublicSetInitial comp(&eng);
         comp.loadUrl(testFileUrl("variantBasedInitialization.qml"));
         QScopedPointer<QObject> obj { comp.beginCreate(eng.rootContext()) };
         QVERIFY(obj);
@@ -728,8 +776,6 @@ void tst_qqmlcomponent::testSetInitialProperties()
                                              });
 #undef ASJSON
         comp.completeCreate();
-        if (!comp.errors().empty())
-            qDebug() << comp.errorString() << comp.errors();
         QVERIFY(comp.errors().empty());
         QCOMPARE(obj->property("i"), 42);
         QCOMPARE(obj->property("b"), true);
@@ -751,13 +797,20 @@ void tst_qqmlcomponent::testSetInitialProperties()
 
     }
     {
+        // createWithInitialProperties convenience function
+        QQmlComponent comp(&eng);
+        comp.loadUrl(testFileUrl("requiredNotSet.qml"));
+        QScopedPointer<QObject> obj {comp.createWithInitialProperties( QVariantMap { {QLatin1String("i"), QJsonValue{42}}  })};
+        QVERIFY(obj);
+        QCOMPARE(obj->property("i"), 42);
+    }
+    {
         // createWithInitialProperties: setting a nonexistent property
         QQmlComponent comp(&eng);
         comp.loadUrl(testFileUrl("allJSONTypes.qml"));
         QScopedPointer<QObject> obj {
             comp.createWithInitialProperties(QVariantMap { {"notThePropertiesYoureLookingFor", 42} })
         };
-        qDebug() << comp.errorString();
         QVERIFY(obj);
         QVERIFY(comp.errorString().contains("Could not set property notThePropertiesYoureLookingFor"));
     }