X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7333c0ef82d54cd2ed21b58fb4fdbcce4f9c9ab6..30f6914ba1d999b84c28fc84a3cf0fdbf9cc326f:/interface/wx/event.h

diff --git a/interface/wx/event.h b/interface/wx/event.h
index fa47fbbafa..cbe556d867 100644
--- a/interface/wx/event.h
+++ b/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.
 
-
-    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.
+    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.
+
+
+    @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