Add ObjectInstances.findQuickWindow and passive-instrumenter exampleHEADmaster

This is a means of instrumenting any pure-QML application to generate an
object diagram showing the items and related objects belonging to the
first top-level window that can be found.

Using a Timer for that is kindof crude; perhaps we should rather
have a separate WindowFinder object that can emit a signal when a
new top-level window is discovered, or something like that. Or use
a Shortcut to trigger it manually. But it works well enough for now.

Change-Id: Ib2d82dfd6fbd4da4b46fbaadb08de2c5e649ffe6
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

3 files changed, 49 insertions, 0 deletions

diff --git a/examples/objectInstancesTimer.qml b/examples/objectInstancesTimer.qml
new file mode 100644
index 0000000..28a336a
--- /dev/null
+++ b/examples/objectInstancesTimer.qml
@@ -0,0 +1,29 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+import QtQml
+import Qt.labs.UmlQuick.Generators
+
+/*
+    This is a means of instrumenting any pure-QML application to generate an
+    object diagram showing the items and related objects belonging to
+    the first top-level window that can be found. Run it like this,
+    and it will write out a .dot file after 2 seconds:
+
+    qml objectInstancesTimer.qml testApplication.qml
+*/
+ObjectInstances {
+    id: oi
+    outputPrefix: "objects-"
+
+    property var timer: Timer {
+        interval: 2000
+        running: true
+        onTriggered: {
+            // TODO use some separate WindowFinder object instead of an invokable function;
+            // somehow that should avoid the need for a Timer
+            oi.root = findQuickWindow()
+            oi.generate()
+        }
+    }
+}
diff --git a/src/generators/objectinstances.cpp b/src/generators/objectinstances.cpp
index e781691..9fea31a 100644
--- a/src/generators/objectinstances.cpp
+++ b/src/generators/objectinstances.cpp
@@ -7,6 +7,7 @@
 #include <QDateTime>
 #include <QDebug>
 #include <QFile>
+#include <QGuiApplication>
 #include <QQuickItem>
 #include <QStringList>
 #include <private/qobject_p.h>
@@ -145,6 +146,23 @@ void ObjectInstances::generate()
     }
 }
 
+/*!
+    Returns the first instance of a QQuickWindow that can be found within the
+    same process.
+
+    This is useful when you use the qml tool to instrument a pre-existing
+    unmodified QML file that has a top-level Window or Item: see
+    \c examples/objectInstancesTimer.qml
+*/
+QQuickWindow *ObjectInstances::findQuickWindow()
+{
+    for (auto *win : qGuiApp->topLevelWindows()) {
+        if (auto *qwin = qobject_cast<QQuickWindow *>(win))
+            return qwin;
+    }
+    return nullptr;
+}
+
 void ObjectInstances::writeDot(const QString &plainFilePath, const QObject *o)
 {
     QString filePath = plainFilePath + u".dot"_s;
diff --git a/src/generators/objectinstances_p.h b/src/generators/objectinstances_p.h
index 7630743..142d84e 100644
--- a/src/generators/objectinstances_p.h
+++ b/src/generators/objectinstances_p.h
@@ -6,6 +6,7 @@
 
 #include <QFile>
 #include <QQmlEngine>
+#include <QQuickWindow>
 
 QT_BEGIN_NAMESPACE
 
@@ -44,6 +45,7 @@ public:
     void setRoot(QObject *newRoot);
 
     Q_INVOKABLE void generate();
+    Q_INVOKABLE QQuickWindow *findQuickWindow();
 
     ColorSource nodeColorSource() const;
     void setNodeColorSource(ColorSource newNodeColorSource);