Add an error signal to QQuickWindow

When nothing is connected to this signal, an error will be printed or,
in case of Windows, a message box will be shown. If there is something
connected, it is up to the application to handle the error.

[ChangeLog] Added a new sceneGraphError() signal to QQuickWindow
which applications can use to detect errors like OpenGL context creation
failures and react in their own custom ways.

Task-number: QTBUG-36138
Change-Id: I33b1e5e0e3f25872af67c5bb5ae937e3470b25f3
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@digia.com>

3 files changed, 48 insertions, 0 deletions

diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 588120a51a..014fb51572 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -2675,6 +2675,17 @@ void QQuickWindowPrivate::updateDirtyNode(QQuickItem *item)
 
 }
 
+bool QQuickWindowPrivate::emitError(QQuickWindow::SceneGraphError error, const QString &msg)
+{
+    Q_Q(QQuickWindow);
+    static const QMetaMethod errorSignal = QMetaMethod::fromSignal(&QQuickWindow::sceneGraphError);
+    if (q->isSignalConnected(errorSignal)) {
+        emit q->sceneGraphError(error, msg);
+        return true;
+    }
+    return false;
+}
+
 void QQuickWindow::maybeUpdate()
 {
     Q_D(QQuickWindow);
@@ -2750,6 +2761,21 @@ QOpenGLContext *QQuickWindow::openglContext() const
  */
 
 /*!
+    \fn void QQuickWindow::sceneGraphError(SceneGraphError error, const QString &message)
+
+    This signal is emitted when an error occurred during scene graph initialization.
+
+    Applications should connect to this signal if they wish to handle errors,
+    like OpenGL context creation failures, in a custom way. When no slot is
+    connected to the signal, the behavior will be different: Quick will print
+    the message, or show a message box, and terminate the application.
+
+    This signal will be emitted from the gui thread.
+
+    \since 5.3
+ */
+
+/*!
     \class QQuickCloseEvent
     \internal
     \since 5.1
@@ -2983,6 +3009,20 @@ QQmlIncubationController *QQuickWindow::incubationController() const
  */
 
 /*!
+    \enum QQuickWindow::SceneGraphError
+
+    This enum describes the error in a sceneGraphError() signal.
+
+    \value ContextNotAvailable OpenGL context creation failed. This typically means that
+    no suitable OpenGL implementation was found, for example because no graphics drivers
+    are installed and so no OpenGL 2 support is present. On mobile and embedded boards
+    that use OpenGL ES such an error is likely to indicate issues in the windowing system
+    integration and possibly an incorrect configuration of Qt.
+
+    \since 5.3
+ */
+
+/*!
     \fn void QQuickWindow::beforeSynchronizing()
 
     This signal is emitted before the scene graph is synchronized with the QML state.
diff --git a/src/quick/items/qquickwindow.h b/src/quick/items/qquickwindow.h
index ced232467b..8be6cc88b7 100644
--- a/src/quick/items/qquickwindow.h
+++ b/src/quick/items/qquickwindow.h
@@ -79,6 +79,11 @@ public:
 
     Q_DECLARE_FLAGS(CreateTextureOptions, CreateTextureOption)
 
+    enum SceneGraphError {
+        ContextNotAvailable = 1
+    };
+    Q_ENUMS(SceneGraphError)
+
     QQuickWindow(QWindow *parent = 0);
 
     virtual ~QQuickWindow();
@@ -142,6 +147,7 @@ Q_SIGNALS:
     Q_REVISION(1) void closing(QQuickCloseEvent *close);
     void colorChanged(const QColor &);
     Q_REVISION(1) void activeFocusItemChanged();
+    void sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message);
 
 public Q_SLOTS:
     void update();
diff --git a/src/quick/items/qquickwindow_p.h b/src/quick/items/qquickwindow_p.h
index 5f61403a40..4fb3d0fa08 100644
--- a/src/quick/items/qquickwindow_p.h
+++ b/src/quick/items/qquickwindow_p.h
@@ -184,6 +184,8 @@ public:
 
     bool isRenderable() const;
 
+    bool emitError(QQuickWindow::SceneGraphError error, const QString &msg);
+
     QQuickItem::UpdatePaintNodeData updatePaintNodeData;
 
     QQuickItem *dirtyItemList;