added wxKeyEvent::GetModifiers()

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

docs/changes.txt

@@ -13,6 +13,7 @@ All:
 All (GUI):
 
 - Added wxTreeBook.
+- Added wxKeyEvent::GetModifiers()
 - Added wxDialog::SetEscapeId().
 - wxItemContainerImmutable::FindString unified (affects wxRadioBox, wxListBox,
   wxComboBox and wxChoice).

docs/latex/wx/constant.tex

@@ -7,5 +7,6 @@ This chapter describes the constants defined by wxWidgets.
 \input cppconst.tex
 \input stdevtid.tex
 \input keycode.tex
+\input keymod.tex
 \input langcodes.tex
 \input stockitems.tex

docs/latex/wx/keyevent.tex

@@ -83,6 +83,9 @@ functions that take a wxKeyEvent argument.
 
 \member{bool}{m\_altDown}
 
+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+
 true if the Alt key is pressed down.
 
 
@@ -90,6 +93,9 @@ true if the Alt key is pressed down.
 
 \member{bool}{m\_controlDown}
 
+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+
 true if control is pressed down.
 
 
@@ -97,6 +103,9 @@ true if control is pressed down.
 
 \member{long}{m\_keyCode}
 
+\textbf{Deprecated: } Please use \helpref{GetKeyCode}{wxkeyeventgetkeycode}
+instead!
+
 Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers.
 
 
@@ -104,6 +113,9 @@ Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers.
 
 \member{bool}{m\_metaDown}
 
+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+
 true if the Meta key is pressed down.
 
 
@@ -111,6 +123,9 @@ true if the Meta key is pressed down.
 
 \member{bool}{m\_shiftDown}
 
+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+
 true if shift is pressed down.
 
 
@@ -118,6 +133,8 @@ true if shift is pressed down.
 
 \member{int}{m\_x}
 
+\textbf{Deprecated: } Please use \helpref{GetX}{wxkeyeventgetx} instead!
+
 X position of the event.
 
 
@@ -125,6 +142,8 @@ X position of the event.
 
 \member{int}{m\_y}
 
+\textbf{Deprecated: } Please use \helpref{GetY}{wxkeyeventgety} instead!
+
 Y position of the event.
 
 
@@ -141,18 +160,21 @@ Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CH
 
 Returns true if the Alt key was down at the time of the key event.
 
+Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use
+correctly than this function so you should consider using it in new code.
+
 
 \membersection{wxKeyEvent::CmdDown}\label{wxkeyeventcmddown}
 
 \constfunc{bool}{CmdDown}{\void}
 
-"Cmd" is a pseudo key which is the same as Control for PC and Unix platforms
+\textsc{Cmd} is a pseudo key which is the same as Control for PC and Unix
-but the special "Apple" (a.k.a as "Command") key under Macs: it makes often
+platforms but the special \textsc{Apple} (a.k.a as \textsc{Command}) key under
-sense to use it instead of, say, ControlDown() because Cmd key is used for the
+Macs: it makes often sense to use it instead of, say, ControlDown() because Cmd
-same thing under Mac as Ctrl elsewhere (but Ctrl still exists, just not used
+key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still
-for this purpose under Mac). So for non-Mac platforms this is the same as 
+exists, just not used for this purpose under Mac). So for non-Mac platforms
-\helpref{ControlDown()}{wxkeyeventcontroldown} and under Mac this is the same
+this is the same as \helpref{ControlDown()}{wxkeyeventcontroldown} and under
-as \helpref{MetaDown()}{wxkeyeventmetadown}.
+Mac this is the same as \helpref{MetaDown()}{wxkeyeventmetadown}.
 
 
 \membersection{wxKeyEvent::ControlDown}\label{wxkeyeventcontroldown}
@@ -161,6 +183,9 @@ as \helpref{MetaDown()}{wxkeyeventmetadown}.
 
 Returns true if the control key was down at the time of the key event.
 
+Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use
+correctly than this function so you should consider using it in new code.
+
 
 \membersection{wxKeyEvent::GetKeyCode}\label{wxkeyeventgetkeycode}
 
@@ -177,6 +202,36 @@ charset. You can obtain the corresponding Unicode character using
 \helpref{GetUnicodeKey}{wxkeyeventgetunicodekey}.
 
 
+\membersection{wxKeyEvent::GetModifiers}\label{wxkeyeventgetmodifiers}
+
+\constfunc{int}{GetModifiers}{\void}
+
+Return the bitmask of modifier keys which were pressed when this event
+happened. See \helpref{key modifier constants}{keymodifiers} for the full list
+of modifiers.
+
+Notice that this function is easier to use correctly than, for example, 
+\helpref{ControlDown}{wxkeyeventcontroldown} because when using the latter you
+also have to remember to test that none of the other modifiers is pressed:
+
+\begin{verbatim}
+    if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
+        ... handle Ctrl-XXX ...
+\end{verbatim}
+
+and forgetting to do it can result in serious program bugs (e.g. program not
+working with European keyboard layout where \textsc{AltGr} key which is seen by
+the program as combination of \textsc{Ctrl} and \textsc{Alt} is used). On the
+other hand, you can simply write
+
+\begin{verbatim}
+    if ( GetModifiers() == wxMOD_CONTROL )
+        ... handle Ctrl-XXX ...
+\end{verbatim}
+
+with this function.
+
+
 \membersection{wxKeyEvent::GetPosition}\label{wxkeyeventgetposition}
 
 \constfunc{wxPoint}{GetPosition}{\void}
@@ -250,6 +305,9 @@ be still processed normally).
 
 Returns true if the Meta key was down at the time of the key event.
 
+Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use
+correctly than this function so you should consider using it in new code.
+
 
 \membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown}
 
@@ -257,3 +315,6 @@ Returns true if the Meta key was down at the time of the key event.
 
 Returns true if the shift key was down at the time of the key event.
 
+Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use
+correctly than this function so you should consider using it in new code.
+

docs/latex/wx/keymod.tex

@@ -0,0 +1,34 @@
+\section{Key Modifiers}\label{keymodifiers}
+
+\wxheading{Include files}
+
+<wx/defs.h>
+
+The following key modifier constants are defined:
+
+{\small
+\begin{verbatim}
+    enum wxKeyModifier
+    {
+        wxMOD_NONE      = 0x0000,
+        wxMOD_ALT       = 0x0001,
+        wxMOD_CONTROL   = 0x0002,
+        wxMOD_ALTGR     = wxMOD_ALT | wxMOD_CONTROL,
+        wxMOD_SHIFT     = 0x0004,
+        wxMOD_META      = 0x0008,
+    #if defined(__WXMAC__) || defined(__WXCOCOA__)
+        wxMOD_CMD       = wxMOD_META,
+    #else
+        wxMOD_CMD       = wxMOD_CONTROL,
+    #endif
+        wxMOD_ALL       = 0xffff
+    };
+\end{verbatim}
+}
+
+Notice that \texttt{wxMOD\_CMD} should be used instead of 
+\texttt{wxMOD\_CONTROL} in portable code to account for the fact that although 
+\textsc{Control} modifier exists under Mac OS, it is not used for the same
+purpose as under Windows or Unix there while the special Mac-specific 
+\textsc{Command} modifier is used in exactly the same way.
+

include/wx/defs.h

@@ -2150,16 +2150,23 @@ enum wxKeyCode
     WXK_SPECIAL20
 };
 
-#if wxUSE_HOTKEY
+/* This enum contains bit mask constants used in wxKeyEvent */
-enum wxHotkeyModifier
+enum wxKeyModifier
 {
-    wxMOD_NONE = 0,
+    wxMOD_NONE      = 0x0000,
-    wxMOD_ALT = 1,
+    wxMOD_ALT       = 0x0001,
-    wxMOD_CONTROL = 2,
+    wxMOD_CONTROL   = 0x0002,
-    wxMOD_SHIFT = 4,
+    wxMOD_ALTGR     = wxMOD_ALT | wxMOD_CONTROL,
-    wxMOD_WIN = 8
+    wxMOD_SHIFT     = 0x0004,
-};
+    wxMOD_META      = 0x0008,
+    wxMOD_WIN       = wxMOD_META,
+#if defined(__WXMAC__) || defined(__WXCOCOA__)
+    wxMOD_CMD       = wxMOD_META,
+#else
+    wxMOD_CMD       = wxMOD_CONTROL,
 #endif
+    wxMOD_ALL       = 0xffff
+};
 
 /*  Mapping modes (same values as used by Windows, don't change) */
 enum

include/wx/event.h

@@ -935,11 +935,22 @@ public:
     wxKeyEvent(wxEventType keyType = wxEVT_NULL);
     wxKeyEvent(const wxKeyEvent& evt);
 
+    // can be used check if the key event has exactly the given modifiers:
+    // "GetModifiers() = wxMOD_CONTROL" is easier to write than "ControlDown()
+    // && !MetaDown() && !AltDown() && !ShiftDown()"
+    int GetModifiers() const
+    {
+        return (m_controlDown ? wxMOD_CONTROL : 0) |
+               (m_shiftDown ? wxMOD_SHIFT : 0) |
+               (m_metaDown ? wxMOD_META : 0) |
+               (m_altDown ? wxMOD_ALT : 0);
+    }
+
     // Find state of shift/control keys
     bool ControlDown() const { return m_controlDown; }
+    bool ShiftDown() const { return m_shiftDown; }
     bool MetaDown() const { return m_metaDown; }
     bool AltDown() const { return m_altDown; }
-    bool ShiftDown() const { return m_shiftDown; }
 
     // "Cmd" is a pseudo key which is Control for PC and Unix platforms but
     // Apple ("Command") key under Macs: it makes often sense to use it instead
@@ -1029,10 +1040,13 @@ public:
 
     long          m_keyCode;
 
+    // TODO: replace those with a single m_modifiers bitmask of wxMOD_XXX?
     bool          m_controlDown;
     bool          m_shiftDown;
     bool          m_altDown;
     bool          m_metaDown;
+
+    // FIXME: what is this for? relation to m_rawXXX?
     bool          m_scanCode;
 
 #if wxUSE_UNICODE