[gtk/matthiasc/for-master: 23/23] wayland: Add a comment about keyboard state handling

[Matthias Clasen <matthiasc src gnome org>]

commit 715bb0699185f728fb23c23db0819879576d4e44
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Apr 2 17:40:44 2020 -0400

    wayland: Add a comment about keyboard state handling
    
    Clarify a point that took me a few hours to fully track
    down, so lets preserve what I found for the next poor
    sould coming this way.

 gdk/wayland/gdkdevice-wayland.c | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
---
diff --git a/gdk/wayland/gdkdevice-wayland.c b/gdk/wayland/gdkdevice-wayland.c
index 0e1ac1d283..8462be55cd 100644
--- a/gdk/wayland/gdkdevice-wayland.c
+++ b/gdk/wayland/gdkdevice-wayland.c
@@ -2160,6 +2160,21 @@ keyboard_handle_modifiers (void               *data,
   direction = gdk_keymap_get_direction (keymap);
   xkb_state = _gdk_wayland_keymap_get_xkb_state (keymap);
 
+  /* Note: the docs for xkb_state_update mask state that all parameters
+   * must be passed, or we may end up with an 'incoherent state. But the
+   * Wayland modifiers event only includes a single group field, so we
+   * can't pass depressed/latched/locked groups.
+   *
+   * We assume that the compositor is sending us the 'effective' group
+   * (the protocol is not clear on that point), and pass it as the depressed
+   * group - we are basically pretending that the user holds down a key for
+   * this group at all times.
+   *
+   * This means that our xkb_state would answer a few questions differently
+   * from the compositors xkb_state - e.g. if you asked it about the latched
+   * group. But nobody is asking it those questions, so it does not really
+   * matter. We hope.
+   */
   xkb_state_update_mask (xkb_state, mods_depressed, mods_latched, mods_locked, group, 0, 0);
 
   seat->key_modifiers = gdk_keymap_get_modifier_state (keymap);