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, 47 insertions, 1 deletions

diff --git a/src/qml/qml/qqmlincubator.cpp b/src/qml/qml/qqmlincubator.cpp
index bc06226cbf..7b3ae31c08 100644
--- a/src/qml/qml/qqmlincubator.cpp
+++ b/src/qml/qml/qqmlincubator.cpp
@@ -43,6 +43,7 @@
 
 #include "qqmlexpression_p.h"
 #include "qqmlobjectcreator_p.h"
+#include <private/qqmlcomponent_p.h>
 
 void QQmlEnginePrivate::incubate(QQmlIncubator &i, QQmlContextData *forContext)
 {
@@ -296,6 +297,20 @@ void QQmlIncubatorPrivate::incubate(QQmlInstantiationInterrupt &i)
         tresult = creator->create(subComponentToCreate, /*parent*/nullptr, &i);
         if (!tresult)
             errors = creator->errors;
+        else {
+           RequiredProperties& requiredProperties = creator->requiredProperties();
+           for (auto it = initialProperties.cbegin(); it != initialProperties.cend(); ++it) {
+               auto component = tresult;
+               auto name = it.key();
+               QQmlProperty prop = QQmlComponentPrivate::removePropertyFromRequired(component, name, requiredProperties);
+               if (!prop.isValid() || !prop.write(it.value())) {
+                   QQmlError error{};
+                   error.setUrl(compilationUnit->url());
+                   error.setDescription(QLatin1String("Could not set property %1").arg(name));
+                   errors.push_back(error);
+               }
+           }
+        }
         enginePriv->dereferenceScarceResources();
 
         if (watcher.hasRecursed())
@@ -312,8 +327,14 @@ void QQmlIncubatorPrivate::incubate(QQmlInstantiationInterrupt &i)
             ddata->indestructible = true;
             ddata->explicitIndestructibleSet = true;
             ddata->rootObjectInCreation = false;
-            if (q)
+            if (q) {
                 q->setInitialState(result);
+                if (!creator->requiredProperties().empty()) {
+                    const auto& unsetRequiredProperties = creator->requiredProperties();
+                    for (const auto& unsetRequiredProperty: unsetRequiredProperties)
+                        errors << QQmlComponentPrivate::unsetRequiredPropertyToQQmlError(unsetRequiredProperty);
+                }
+            }
         }
 
         if (watcher.hasRecursed())
@@ -657,6 +678,31 @@ QObject *QQmlIncubator::object() const
 }
 
 /*!
+Return a list of properties which are required but haven't been set yet.
+This list can be modified, so that subclasses which implement special logic
+setInitialProperties can mark properties set there as no longer required.
+
+\sa QQmlIncubator::setInitialProperties
+\since 5.15
+*/
+RequiredProperties &QQmlIncubatorPrivate::requiredProperties()
+{
+    return creator->requiredProperties();
+}
+
+/*!
+Stores a mapping from property names to initial values with which the incubated
+component will be initialized
+
+\sa QQmlComponent::setInitialProperties
+\since 5.15
+*/
+void QQmlIncubator::setInitialProperties(const QVariantMap &initialProperties)
+{
+    d->initialProperties = initialProperties;
+}
+
+/*!
 Called when the status of the incubator changes.  \a status is the new status.
 
 The default implementation does nothing.