Add QQuickItemGrabResult::saveToFile(QUrl) overload

FileDialog provdes an url; alternatively something like
StandardPaths.writableLocation(StandardPaths.PicturesLocation) could
provide a good folder in which to save a screenshot file: also in the
form of a QUrl, but in that case, one might want to append a generated
filename.  Appending converts the URL to a string, and QUrl has no
QML-facing API to help modify it.  So depending on how it's done,
saveToFile() could be called with a plain filename, a path,
file:///path/to/file.png as a string or as a QUrl; it should now be able
to deal with all of those.

Also monospaced the true/false constants in qdoc comments.

Fixes: QTBUG-56436
Change-Id: I6058a52d3c64e243e44d4487f2b35fa31b1636fe
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

2 files changed, 25 insertions, 4 deletions

diff --git a/src/quick/items/qquickitemgrabresult.cpp b/src/quick/items/qquickitemgrabresult.cpp
index 41e9b2fe90..cb2f12ea8b 100644
--- a/src/quick/items/qquickitemgrabresult.cpp
+++ b/src/quick/items/qquickitemgrabresult.cpp
@@ -179,22 +179,42 @@ QQuickItemGrabResult::QQuickItemGrabResult(QObject *parent)
 /*!
  * \qmlmethod bool QtQuick::ItemGrabResult::saveToFile(fileName)
  *
- * Saves the grab result as an image to \a fileName. Returns true
- * if successful; otherwise returns false.
+ * Saves the grab result as an image to \a fileName. Returns \c true
+ * if successful; otherwise returns \c false.
  */
 
 /*!
- * Saves the grab result as an image to \a fileName. Returns true
- * if successful; otherwise returns false.
+ * Saves the grab result as an image to \a fileName. Returns \c true
+ * if successful; otherwise returns \c false.
  *
  * \note In Qt versions prior to 5.9, this function is marked as non-\c{const}.
  */
+// ### Qt 7: remove and keep only QUrl overload
 bool QQuickItemGrabResult::saveToFile(const QString &fileName) const
 {
     Q_D(const QQuickItemGrabResult);
+    if (fileName.startsWith(QLatin1String("file:/")))
+        return saveToFile(QUrl(fileName));
     return d->image.save(fileName);
 }
 
+/*!
+ * \since 6.2
+ * Saves the grab result as an image to \a filePath, which must refer to a
+ * \l{QUrl::isLocalFile}{local file name} with a
+ * \l{QImageWriter::supportedImageFormats()}{supported image format} extension.
+ * Returns \c true if successful; otherwise returns \c false.
+ */
+bool QQuickItemGrabResult::saveToFile(const QUrl &filePath) const
+{
+    Q_D(const QQuickItemGrabResult);
+    if (!filePath.isLocalFile()) {
+        qWarning() << "saveToFile can only save to a file on the local filesystem";
+        return false;
+    }
+    return d->image.save(filePath.toLocalFile());
+}
+
 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
 #if QT_DEPRECATED_SINCE(5, 15)
 /*!
diff --git a/src/quick/items/qquickitemgrabresult.h b/src/quick/items/qquickitemgrabresult.h
index 96d18b907b..a055c0638b 100644
--- a/src/quick/items/qquickitemgrabresult.h
+++ b/src/quick/items/qquickitemgrabresult.h
@@ -75,6 +75,7 @@ public:
 #endif
 #endif
     Q_INVOKABLE bool saveToFile(const QString &fileName) const;
+    Q_INVOKABLE bool saveToFile(const QUrl &fileName) const;
 
 protected:
     bool event(QEvent *) override;