Document and safeguard usage of custom schemes

The change improves the documentation of QWebEngineUrlSchemeHandler to
notify the requirement of registering a custom scheme before installing
a custom scheme handler.

Also start showing warnings when
QWebEngineProfile::installUrlSchemeHandler() is called before a scheme
is registered. Also show warnings when installing the handler using
QML.

Task-number: QTBUG-72079
Change-Id: If249592ea43fe2f9ad587a6ff4e8c9dedcc5d3d3
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Kai Koehne <kai.koehne@qt.io>

2 files changed, 45 insertions, 4 deletions

diff --git a/src/core/api/qwebengineurlscheme.cpp b/src/core/api/qwebengineurlscheme.cpp
index f36f3335b..d63599163 100644
--- a/src/core/api/qwebengineurlscheme.cpp
+++ b/src/core/api/qwebengineurlscheme.cpp
@@ -84,8 +84,10 @@ public:
   URLs.
 
   Custom URL schemes must be configured early at application startup, before
-  creating any Qt WebEngine classes. The configuration applies globally to all
-  profiles.
+  creating any Qt WebEngine classes. In general this means the schemes need to be configured before
+  a QGuiApplication or QApplication instance is created.
+
+  Every registered scheme configuration applies globally to all profiles.
 
   \code
   int main(int argc, char **argv)
diff --git a/src/core/api/qwebengineurlschemehandler.cpp b/src/core/api/qwebengineurlschemehandler.cpp
index 94b85c42b..6f06b2c6e 100644
--- a/src/core/api/qwebengineurlschemehandler.cpp
+++ b/src/core/api/qwebengineurlschemehandler.cpp
@@ -48,12 +48,51 @@ QT_BEGIN_NAMESPACE
     \brief The QWebEngineUrlSchemeHandler is a base class for handling custom URL schemes.
     \since 5.6
 
-    To implement a custom URL scheme for QtWebEngine, you must write a class derived from this class,
-    and reimplement requestStarted(). Then install it via QWebEngineProfile::installUrlSchemeHandler()
+    To implement a custom URL scheme for QtWebEngine, you first have to create an instance of
+    QWebEngineUrlScheme and register it using QWebEngineUrlScheme::registerScheme().
+
+    \note Make sure that you create and register the scheme object \e before the QGuiApplication
+    or QApplication object is instantiated.
+
+    Then you must create a class derived from QWebEngineUrlSchemeHandler,
+    and reimplement the requestStarted() method.
+
+    Finally, install the scheme handler object via QWebEngineProfile::installUrlSchemeHandler()
     or QQuickWebEngineProfile::installUrlSchemeHandler().
 
+    \code
+
+    class MySchemeHandler : public QWebEngineUrlSchemeHandler
+    {
+    public:
+        MySchemeHandler(QObject *parent = nullptr);
+        void requestStarted(QWebEngineUrlRequestJob *request)
+        {
+            // ....
+        }
+    };
+
+    int main(int argc, char **argv)
+    {
+        QWebEngineUrlScheme scheme("myscheme");
+        scheme.setSyntax(QWebEngineUrlScheme::Syntax::HostAndPort);
+        scheme.setDefaultPort(2345);
+        scheme.setFlags(QWebEngineUrlScheme::SecureScheme);
+        QWebEngineUrlScheme::registerScheme(scheme);
+
+        // ...
+        QApplication app(argc, argv);
+        // ...
+
+        // installUrlSchemeHandler does not take ownership of the handler.
+        MySchemeHandler *handler = new MySchemeHandler(parent);
+        QWebEngineProfile::defaultProfile()->installUrlSchemeHandler("myscheme", handler);
+    }
+    \endcode
+
     \inmodule QtWebEngineCore
 
+    \sa {QWebEngineUrlScheme}, {WebEngine Widgets WebUI Example}
 */
 
 /*!