Document sendFullKeyEvent() and sendKeyEvent() limitations

Pick-to: 6.5
Task-number: QTBUG-112853
Change-Id: I5ae7ee194e8415c5e34ecde2d93086885866abfd
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>

1 files changed, 8 insertions, 0 deletions

diff --git a/src/compositor/compositor_api/qwaylandseat.cpp b/src/compositor/compositor_api/qwaylandseat.cpp
index ee447da5..375202fb 100644
--- a/src/compositor/compositor_api/qwaylandseat.cpp
+++ b/src/compositor/compositor_api/qwaylandseat.cpp
@@ -434,6 +434,11 @@ void QWaylandSeat::sendFullTouchEvent(QWaylandSurface *surface, QTouchEvent *eve
 
 /*!
  * Sends the \a event to the keyboard device.
+ *
+ * \note The \a event should correspond to an actual keyboard key in the current mapping.
+ * For example, \c Qt::Key_Exclam is normally not a separate key: with most keyboards the
+ * exclamation mark is produced with Shift + 1. In that case, to send an exclamation mark
+ * key press event, use \c{QKeyEvent(QEvent::KeyPress, Qt::Key_1, Qt::ShiftModifier)}.
  */
 void QWaylandSeat::sendFullKeyEvent(QKeyEvent *event)
 {
@@ -513,6 +518,9 @@ void QWaylandSeat::sendFullKeyEvent(QKeyEvent *event)
  * Sends a key press (if \a pressed is \c true) or release (if \a pressed is \c false)
  * event of a key \a qtKey to the keyboard device.
  *
+ * \note This function does not support key events that require modifiers, such as \c Qt::Key_Exclam.
+ * Use \l{sendFullKeyEvent} instead.
+ *
  * \since 5.12
  */
 void QWaylandSeat::sendKeyEvent(int qtKey, bool pressed)