Rename QUrlResourceProvider to QTextDocumentResourceProvider

While the class name is now a bit more than a mouthful, it's purpose
is very narrowly tied to QTextDocument, so don't use a very generic
name for it. That resources are provided based on a URL is to some
degree an implementation detail, and URLs are resource locators so
we don't need that in the class name.

Address code review comment for 6.1. Add documentation and links to
existing APIs with a similar purpose.

Task-number: QTBUG-90211
Task-number: QTBUG-92208
Pick-to: 6.1
Change-Id: I4f09057cc2f53a5595513c1c9422e6ccaad6ca13
Reviewed-by: Kai Koehne <kai.koehne@qt.io>

6 files changed, 41 insertions, 27 deletions

diff --git a/src/gui/text/qtextdocument.cpp b/src/gui/text/qtextdocument.cpp
index 2e9293eb99..9234714f64 100644
--- a/src/gui/text/qtextdocument.cpp
+++ b/src/gui/text/qtextdocument.cpp
@@ -46,7 +46,7 @@
 #include "qtextdocumentfragment_p.h"
 #include "qtexttable.h"
 #include "qtextlist.h"
-#include "qurlresourceprovider.h"
+#include "qtextdocumentresourceprovider.h"
 #include <qdebug.h>
 #if QT_CONFIG(regularexpression)
 #include <qregularexpression.h>
@@ -2094,7 +2094,7 @@ QVariant QTextDocument::resource(int type, const QUrl &name) const
             if (!r.isValid()) {
                 if (d->resourceProvider)
                     r = d->resourceProvider->resource(url);
-                else if (auto defaultProvider = QUrlResourceProvider::defaultProvider())
+                else if (auto defaultProvider = QTextDocumentResourceProvider::defaultProvider())
                     r = defaultProvider->resource(url);
             }
         }
@@ -2132,7 +2132,7 @@ void QTextDocument::addResource(int type, const QUrl &name, const QVariant &reso
 
     Returns the resource provider for this text document.
 */
-QUrlResourceProvider *QTextDocument::resourceProvider() const
+QTextDocumentResourceProvider *QTextDocument::resourceProvider() const
 {
     Q_D(const QTextDocument);
     return d->resourceProvider;
@@ -2145,7 +2145,7 @@ QUrlResourceProvider *QTextDocument::resourceProvider() const
 
     \note The text document \e{does not} take ownership of the \a provider.
 */
-void QTextDocument::setResourceProvider(QUrlResourceProvider *provider)
+void QTextDocument::setResourceProvider(QTextDocumentResourceProvider *provider)
 {
     Q_D(QTextDocument);
     d->resourceProvider = provider;
@@ -2167,6 +2167,8 @@ void QTextDocument::setResourceProvider(QUrlResourceProvider *provider)
     loadResource method such as QTextEdit, QTextBrowser
     or a QTextDocument itself then the default implementation tries
     to retrieve the data from the parent.
+
+    \sa QTextDocumentResourceProvider
 */
 QVariant QTextDocument::loadResource(int type, const QUrl &name)
 {
diff --git a/src/gui/text/qtextdocument.h b/src/gui/text/qtextdocument.h
index ea57b697a8..286b1ed299 100644
--- a/src/gui/text/qtextdocument.h
+++ b/src/gui/text/qtextdocument.h
@@ -68,7 +68,7 @@ class QVariant;
 class QRectF;
 class QTextOption;
 class QTextCursor;
-class QUrlResourceProvider;
+class QTextDocumentResourceProvider;
 
 
 namespace Qt
@@ -240,8 +240,8 @@ public:
     QVariant resource(int type, const QUrl &name) const;
     void addResource(int type, const QUrl &name, const QVariant &resource);
 
-    QUrlResourceProvider *resourceProvider() const;
-    void setResourceProvider(QUrlResourceProvider *provider);
+    QTextDocumentResourceProvider *resourceProvider() const;
+    void setResourceProvider(QTextDocumentResourceProvider *provider);
 
     QList<QTextFormat> allFormats() const;
 
diff --git a/src/gui/text/qtextdocument_p.cpp b/src/gui/text/qtextdocument_p.cpp
index 1f2e8d2da2..eb62168a31 100644
--- a/src/gui/text/qtextdocument_p.cpp
+++ b/src/gui/text/qtextdocument_p.cpp
@@ -52,7 +52,7 @@
 #include "qtextdocumentlayout_p.h"
 #include "qtexttable.h"
 #include "qtextengine_p.h"
-#include "qurlresourceprovider.h"
+#include "qtextdocumentresourceprovider.h"
 
 #include <stdlib.h>
 
diff --git a/src/gui/text/qtextdocument_p.h b/src/gui/text/qtextdocument_p.h
index d04113b320..f68cd56d88 100644
--- a/src/gui/text/qtextdocument_p.h
+++ b/src/gui/text/qtextdocument_p.h
@@ -366,7 +366,7 @@ private:
     QMap<int, QTextObject *> objects;
     QMap<QUrl, QVariant> resources;
     QMap<QUrl, QVariant> cachedResources;
-    QUrlResourceProvider *resourceProvider;
+    QTextDocumentResourceProvider *resourceProvider;
     QString defaultStyleSheet;
 
     int lastBlockCount;
diff --git a/src/gui/text/qurlresourceprovider.cpp b/src/gui/text/qtextdocumentresourceprovider.cpp
index 6a50504471..1a03e1bb44 100644
--- a/src/gui/text/qurlresourceprovider.cpp
+++ b/src/gui/text/qtextdocumentresourceprovider.cpp
@@ -37,50 +37,62 @@
 **
 ****************************************************************************/
 
-#include "qurlresourceprovider.h"
+#include "qtextdocumentresourceprovider.h"
 
 #include <QtCore/qatomic.h>
 
 QT_BEGIN_NAMESPACE
 
 /*!
-    \class QUrlResourceProvider
+    \class QTextDocumentResourceProvider
     \inmodule QtGui
     \since 6.1
-    \brief The QUrlResourceProvider is the base class of resource providers for QTextDocument.
+    \brief The QTextDocumentResourceProvider is the base class of resource providers for QTextDocument.
+
+    Override resource() in a subclass, and set a subclass instance on a text document via
+    QTextDocument::setResourceProvider, or on a label via QLabel::setResourceProvider. This
+    allows customizing how resources are loaded in rich text documents without having to subclass
+    QTextDocument or QLabel, respectively.
+
     \note An implementation should be thread-safe if it can be accessed from different threads,
-    e.g. when the default resource provider lives in the main thread and a QTexDocument lives
+    e.g. when the default resource provider lives in the main thread and a QTextDocument lives
     outside the main thread.
 */
 
-static QAtomicPointer<QUrlResourceProvider> qt_provider;
+static QAtomicPointer<QTextDocumentResourceProvider> qt_provider;
 
 /*!
     Destroys the resource provider.
 */
-QUrlResourceProvider::~QUrlResourceProvider()
+QTextDocumentResourceProvider::~QTextDocumentResourceProvider()
 {
     qt_provider.testAndSetRelease(this, nullptr);
 }
 
 /*!
-    \fn virtual QVariant QUrlResourceProvider::resource(const QUrl &url) = 0;
+    \fn virtual QVariant QTextDocumentResourceProvider::resource(const QUrl &url) = 0;
 
     Returns data specified by the \a url.
+
+    \sa QTextDocument::loadResource
 */
 
 /*!
     Returns the default resource provider.
+
+    \sa QTextDocument::loadResource
 */
-QUrlResourceProvider *QUrlResourceProvider::defaultProvider()
+QTextDocumentResourceProvider *QTextDocumentResourceProvider::defaultProvider()
 {
     return qt_provider.loadAcquire();
 }
 
 /*!
     Set the default resource provider to \a provider.
+
+    \sa QTextDocument::loadResource
 */
-void QUrlResourceProvider::setDefaultProvider(QUrlResourceProvider *provider)
+void QTextDocumentResourceProvider::setDefaultProvider(QTextDocumentResourceProvider *provider)
 {
     qt_provider.storeRelease(provider);
 }
diff --git a/src/gui/text/qurlresourceprovider.h b/src/gui/text/qtextdocumentresourceprovider.h
index 088a878d8c..5fd8699e7c 100644
--- a/src/gui/text/qurlresourceprovider.h
+++ b/src/gui/text/qtextdocumentresourceprovider.h
@@ -37,8 +37,8 @@
 **
 ****************************************************************************/
 
-#ifndef QURLRESOURCEPROVIDER_H
-#define QURLRESOURCEPROVIDER_H
+#ifndef QTEXTDOCUMENTRESOURCEPROVIDER_H
+#define QTEXTDOCUMENTRESOURCEPROVIDER_H
 
 #include <QtGui/qtguiglobal.h>
 #include <QtCore/qvariant.h>
@@ -46,18 +46,18 @@
 QT_BEGIN_NAMESPACE
 
 
-class Q_GUI_EXPORT QUrlResourceProvider
+class Q_GUI_EXPORT QTextDocumentResourceProvider
 {
-    Q_DISABLE_COPY(QUrlResourceProvider)
+    Q_DISABLE_COPY(QTextDocumentResourceProvider)
 public:
-    QUrlResourceProvider() = default;
-    virtual ~QUrlResourceProvider();
+    QTextDocumentResourceProvider() = default;
+    virtual ~QTextDocumentResourceProvider();
     virtual QVariant resource(const QUrl &url) = 0;
 
-    static QUrlResourceProvider *defaultProvider();
-    static void setDefaultProvider(QUrlResourceProvider *provider);
+    static QTextDocumentResourceProvider *defaultProvider();
+    static void setDefaultProvider(QTextDocumentResourceProvider *provider);
 };
 
 QT_END_NAMESPACE
 
-#endif // QURLRESOURCEPROVIDER_H
+#endif // QTEXTDOCUMENTRESOURCEPROVIDER_H