document (and check for it with assert) that wxGetKeyState(WXK_[LMR]BUTTON) doesn't work (patch 1156279)

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

docs/latex/wx/function.tex

@@ -2660,9 +2660,14 @@ this language feature but still take advantage of it when it is available.
 
 \func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}}
 
-Returns \true if the key parameter is currently pressed on the keyboard, or
-with modifier keys, (caps lock, etc) if the key is active (the led light is
-on).
+For normal keys, returns \true if the specified key is currently down.
+
+For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
+\true if the key is toggled such that its LED indicator is lit. There is
+currently no way to test whether togglable keys are up or down.
+
+Even though there are virtual key codes defined for mouse buttons, they
+cannot be used with this function currently.
 
 \wxheading{Include files}
 

src/mac/carbon/app.cpp

@@ -1184,6 +1184,9 @@ int wxMacKeyCodeToModifier(wxKeyCode key)
 #ifndef __DARWIN__
 bool wxGetKeyState(wxKeyCode key) //virtual key code if < 10.2.x, else see below
 {
+    wxASSERT_MSG(key != WXK_LBUTTON && key != WXK_RBUTTON && key !=
+        WXK_MBUTTON, wxT("can't use wxGetKeyState() for mouse buttons"));
+
 //if OS X > 10.2 (i.e. 10.2.x)
 //a known apple bug prevents the system from determining led
 //states with GetKeys... can only determine caps lock led

src/mac/classic/app.cpp

@@ -1853,6 +1853,9 @@ int wxKeyCodeToMacModifier(wxKeyCode key)
 
 bool wxGetKeyState(wxKeyCode key) //virtual key code if < 10.2.x, else see below
 {
+    wxASSERT_MSG(key != WXK_LBUTTON && key != WXK_RBUTTON && key !=
+        WXK_MBUTTON, wxT("can't use wxGetKeyState() for mouse buttons"));
+
 #if __WXMAC_CARBON__
 //TODO: Low get map...
    return !!(GetCurrentKeyModifiers() & wxKeyCodeToMacModifier(key)); 

src/mac/corefoundation/hid.cpp

@@ -488,6 +488,9 @@ wxHIDKeyboard* wxHIDModule::sm_keyboard;
 
 bool wxGetKeyState (wxKeyCode key)
 {
+    wxASSERT_MSG(key != WXK_LBUTTON && key != WXK_RBUTTON && key !=
+        WXK_MBUTTON, wxT("can't use wxGetKeyState() for mouse buttons"));
+
     if (!wxHIDModule::sm_keyboard)
     {
         wxHIDModule::sm_keyboard = new wxHIDKeyboard();

src/msw/window.cpp

@@ -5144,6 +5144,9 @@ bool wxGetKeyState(wxKeyCode key)
 {
     bool bVirtual;
 
+    wxASSERT_MSG(key != WXK_LBUTTON && key != WXK_RBUTTON && key !=
+        WXK_MBUTTON, wxT("can't use wxGetKeyState() for mouse buttons"));
+
 //High order with GetAsyncKeyState only available on WIN32
 #ifdef __WIN32__
     //If the requested key is a LED key, return

src/unix/utilsx11.cpp

@@ -764,6 +764,9 @@ KeySym wxCharCodeWXToX(int id)
 
 bool wxGetKeyState(wxKeyCode key)
 {
+    wxASSERT_MSG(key != WXK_LBUTTON && key != WXK_RBUTTON && key !=
+        WXK_MBUTTON, wxT("can't use wxGetKeyState() for mouse buttons"));
+
 #if defined(__WXX11__)
     Display *pDisplay = (Display*) wxApp::GetDisplay();
 #elif defined(__WXGTK__)