EntityLoader: add a status property

And complete the documentation a bit

Change-Id: I3d3520e09456d256ee258d14656e97a08f2727aa
Task-number: QTBUG-57613
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

3 files changed, 64 insertions, 2 deletions

diff --git a/src/quick3d/quick3d/items/quick3dentityloader.cpp b/src/quick3d/quick3d/items/quick3dentityloader.cpp
index 9c82db7ad..9bc9d9d28 100644
--- a/src/quick3d/quick3d/items/quick3dentityloader.cpp
+++ b/src/quick3d/quick3d/items/quick3dentityloader.cpp
@@ -71,6 +71,12 @@ protected:
             Q_ASSERT(priv->m_entity != nullptr);
             priv->m_entity->setParent(m_loader);
             emit m_loader->entityChanged();
+            priv->setStatus(Quick3DEntityLoader::Ready);
+            break;
+        }
+
+        case Loading: {
+            priv->setStatus(Quick3DEntityLoader::Loading);
             break;
         }
 
@@ -78,6 +84,7 @@ protected:
             QQmlEnginePrivate::warning(qmlEngine(m_loader), errors());
             priv->clear();
             emit m_loader->entityChanged();
+            priv->setStatus(Quick3DEntityLoader::Error);
             break;
         }
 
@@ -95,13 +102,21 @@ private:
     \inqmlmodule Qt3D.Core
     \inherits Entity
     \since 5.5
-    \brief Provides the facility to load entities from qml source
+    \brief Provides a way to dynamically load an Entity subtree
 
     An EntityLoader provides the facitily to load predefined set of entities
     from qml source file. EntityLoader itself is an entity and the loaded entity
     tree is set as a child of the loader. The loaded entity tree root can be
     accessed with EntityLoader::entity property.
+
+    \badcode
+        EntityLoader {
+            id: loader
+            source: "./SphereEntity.qml"
+        }
+    \endcode
 */
+
 Quick3DEntityLoader::Quick3DEntityLoader(QNode *parent)
     : QEntity(*new Quick3DEntityLoaderPrivate, parent)
 {
@@ -117,6 +132,10 @@ Quick3DEntityLoader::~Quick3DEntityLoader()
     \qmlproperty QtQml::QtObject EntityLoader::entity
     Holds the loaded entity tree root.
     \readonly
+
+    This property allows access to the content of the loader. It references
+    either a valid Entity object if the status property equals
+    EntityLoader.Ready, it is equal to null otherwise.
 */
 QObject *Quick3DEntityLoader::entity() const
 {
@@ -147,12 +166,30 @@ void Quick3DEntityLoader::setSource(const QUrl &url)
     d->loadFromSource();
 }
 
+/*!
+    \qmlproperty Status Qt3DCore::EntityLoader::status
+
+    Holds the status of the entity loader.
+    \list
+    \li EntityLoader.Null
+    \li EntityLoader.Loading
+    \li EntityLoader.Ready
+    \li EntityLoader.Error
+    \endlist
+ */
+Quick3DEntityLoader::Status Quick3DEntityLoader::status() const
+{
+    Q_D(const Quick3DEntityLoader);
+    return d->m_status;
+}
+
 Quick3DEntityLoaderPrivate::Quick3DEntityLoaderPrivate()
     : QEntityPrivate(),
       m_incubator(nullptr),
       m_context(nullptr),
       m_component(nullptr),
-      m_entity(nullptr)
+      m_entity(nullptr),
+      m_status(Quick3DEntityLoader::Null)
 {
 }
 
@@ -234,6 +271,17 @@ void Quick3DEntityLoaderPrivate::_q_componentStatusChanged(QQmlComponent::Status
     m_component->create(*m_incubator, m_context);
 }
 
+void Quick3DEntityLoaderPrivate::setStatus(Quick3DEntityLoader::Status status)
+{
+    Q_Q(Quick3DEntityLoader);
+    if (status != m_status) {
+        m_status = status;
+        const bool blocked = q->blockNotifications(true);
+        emit q->statusChanged(m_status);
+        q->blockNotifications(blocked);
+    }
+}
+
 } // namespace Quick
 } // namespace Qt3DCore
 
diff --git a/src/quick3d/quick3d/items/quick3dentityloader_p.h b/src/quick3d/quick3d/items/quick3dentityloader_p.h
index 5721af115..9cd0eff2e 100644
--- a/src/quick3d/quick3d/items/quick3dentityloader_p.h
+++ b/src/quick3d/quick3d/items/quick3dentityloader_p.h
@@ -74,7 +74,16 @@ class QT3DQUICKSHARED_PRIVATE_EXPORT Quick3DEntityLoader : public QEntity
     Q_OBJECT
     Q_PROPERTY(QObject *entity READ entity NOTIFY entityChanged)
     Q_PROPERTY(QUrl source READ source WRITE setSource NOTIFY sourceChanged)
+    Q_PROPERTY(Status status READ status NOTIFY statusChanged)
 public:
+    enum Status {
+        Null = 0,
+        Loading,
+        Ready,
+        Error
+    };
+    Q_ENUM(Status)
+
     explicit Quick3DEntityLoader(QNode *parent = 0);
     ~Quick3DEntityLoader();
 
@@ -83,9 +92,12 @@ public:
     QUrl source() const;
     void setSource(const QUrl &url);
 
+    Status status() const;
+
 Q_SIGNALS:
     void entityChanged();
     void sourceChanged();
+    void statusChanged(Status status);
 
 private:
     Q_DECLARE_PRIVATE(Quick3DEntityLoader)
diff --git a/src/quick3d/quick3d/items/quick3dentityloader_p_p.h b/src/quick3d/quick3d/items/quick3dentityloader_p_p.h
index 235870933..1ff1459cb 100644
--- a/src/quick3d/quick3d/items/quick3dentityloader_p_p.h
+++ b/src/quick3d/quick3d/items/quick3dentityloader_p_p.h
@@ -82,6 +82,7 @@ public:
     void loadComponent(const QUrl &source);
 
     void _q_componentStatusChanged(QQmlComponent::Status status);
+    void setStatus(Quick3DEntityLoader::Status status);
 
     static inline Quick3DEntityLoaderPrivate *get(Quick3DEntityLoader *q) { return q->d_func(); }
 
@@ -90,6 +91,7 @@ public:
     QQmlContext *m_context;
     QQmlComponent *m_component;
     QEntity *m_entity;
+    Quick3DEntityLoader::Status m_status;
 };
 
 } // namespace Quick