Generate the same flags for modifier key events in wxGTK as in wxMSW.

Resolve the discrepancy between modifier flags of the key events corresponding
to the modifier key itself between wxMSW and wxGTK by changing the latter to
follow wxMSW behaviour.

Clearly document the now officially correct behaviour of the modifiers for the
key events corresponding to the modifiers keys themselves in the manual.

This fix also makes it unnecessary to work around this bug in the keyboard
unit test so remove it from there.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@65527 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/event.h

@@ -1257,19 +1257,31 @@ enum wxKeyCategoryFlags
     The modifiers keys are @c WXK_SHIFT, @c WXK_CONTROL, @c WXK_ALT and various
     @c WXK_WINDOWS_XXX from ::wxKeyCode enum.
 
+    Modifier keys events are special in one additional aspect: usually the
+    keyboard state associated with a key press is well defined, e.g.
+    wxKeyboardState::ShiftDown() returns @c true only if the Shift key was held
+    pressed when the key that generated this event itself was pressed. There is
+    an ambiguity for the key press events for Shift key itself however. By
+    convention, it is considered to be already pressed when it is pressed and
+    already released when it is released. In other words, @c wxEVT_KEY_DOWN
+    event for the Shift key itself will have @c wxMOD_SHIFT in GetModifiers()
+    and ShiftDown() will return true while the @c wxEVT_KEY_UP event for Shift
+    itself will not have @c wxMOD_SHIFT in its modifiers and ShiftDown() will
+    return false.
 
-    You may discover how the other keys on your system behave interactively by
-    running the @ref page_samples_keyboard wxWidgets sample and pressing some
-    keys in it.
 
-    @b Tip: be sure to call @c event.Skip() for events that you don't process in
-    key event function, otherwise menu shortcuts may cease to work under Windows.
+    @b Tip: You may discover the key codes and modifiers generated by all the
+        keys on your system interactively by running the @ref
+        page_samples_keyboard wxWidgets sample and pressing some keys in it.
 
     @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler
           does not call @c event.Skip() then the corresponding char event
-          (@c EVT_CHAR) will not happen.
-          This is by design and enables the programs that handle both types of
-          events to be a bit simpler.
+          (@c EVT_CHAR) will not happen. This is by design and enables the
+          programs that handle both types of events to avoid processing the
+          same key twice. As a consequence, if you do not want to suppress the
+          @c wxEVT_CHAR events for the keys you handle, always call @c
+          event.Skip() in your @c wxEVT_KEY_DOWN handler. Not doing may also
+          prevent accelerators defined using this key from working.
 
     @note For Windows programmers: The key and char events in wxWidgets are
           similar to but slightly different from Windows @c WM_KEYDOWN and