Enhance QQuickRenderControl docs regarding key events

...and rephrase one of the general description paragraphs to be
more accurate.

Fixes: QTBUG-93489
Change-Id: If238fff84480720a618c8a337fe416cd08ee9b79
Reviewed-by: Andy Nichols <andy.nichols@qt.io>
(cherry picked from commit 6dfed1ee9c8e03780b222a71f6b90fe2016d8994)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 15 insertions, 5 deletions

diff --git a/src/quick/items/qquickrendercontrol.cpp b/src/quick/items/qquickrendercontrol.cpp
index caf5a17dc6..a660bd0ca3 100644
--- a/src/quick/items/qquickrendercontrol.cpp
+++ b/src/quick/items/qquickrendercontrol.cpp
@@ -84,11 +84,15 @@ QT_BEGIN_NAMESPACE
   possible in a hardware accelerated manner, unlike the performance-wise limited
   alternative of using QQuickWindow::grabWindow()
 
-  When using a QQuickRenderControl, the QQuickWindow does not have to be shown
-  or even created at all. This means there will not be an underlying native
-  window for it. Instead, the QQuickWindow instance is associated with the
-  render control, using the overload of the QQuickWindow constructor, and a
-  texture or image object specified via QQuickWindow::setRenderTarget().
+  When using a QQuickRenderControl, the QQuickWindow must not be
+  \l{QWindow::show()}{shown} (it will not be visible on-screen) and there will
+  not be an underlying native window for it. Instead, the QQuickWindow instance
+  is associated with the render control object, using the overload of the
+  QQuickWindow constructor, and a texture or image object specified via
+  QQuickWindow::setRenderTarget(). The QQuickWindow object is still essential,
+  because it represents the Qt Quick scene and provides the bulk of the scene
+  management and event delivery mechanisms. It does not however act as a real
+  on-screen window from the windowing system's perspective.
 
   Management of the graphics devices, contexts, image and texture objects is up
   to the application. The device or context that will be used by Qt Quick must
@@ -130,6 +134,12 @@ QT_BEGIN_NAMESPACE
   To send events, for example mouse or keyboard events, to the scene, use
   QCoreApplication::sendEvent() with the QQuickWindow instance as the receiver.
 
+  For key events it may be also necessary to set the focus manually on the
+  desired item. In practice this involves calling
+  \l{QQuickItem::forceActiveFocus()}{forceActiveFocus()} on the desired item,
+  for example the scene's root item, once it is associated with the scene (the
+  QQuickWindow).
+
   \note In general QQuickRenderControl is supported in combination with all Qt
   Quick backends. However, some functionality, in particular grab(), may not be
   available in all cases.