added wxKeyEvent::GetModifiers()

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

diff --git a/docs/changes.txt b/docs/changes.txt
index dd89687033f5c9df48bd2376308e46546bcba5ea..dd3f96241233f49e0582629396530d7e95289104 100644 (file)
--- a/docs/changes.txt
+++ b/docs/changes.txt
@@ -13,6 +13,7 @@ All:
 All (GUI):
 
 - Added wxTreeBook.
 All (GUI):
 
 - Added wxTreeBook.

+- Added wxKeyEvent::GetModifiers()

 - Added wxDialog::SetEscapeId().
 - wxItemContainerImmutable::FindString unified (affects wxRadioBox, wxListBox,
   wxComboBox and wxChoice).
 - Added wxDialog::SetEscapeId().
 - wxItemContainerImmutable::FindString unified (affects wxRadioBox, wxListBox,
   wxComboBox and wxChoice).

diff --git a/docs/latex/wx/constant.tex b/docs/latex/wx/constant.tex
index 8eb8452dfac956425b58d814d6efc528412d295f..c70570f0c47f56422b081c4eeae7724506b75cc1 100644 (file)
--- a/docs/latex/wx/constant.tex
+++ b/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 cppconst.tex
 \input stdevtid.tex
 \input keycode.tex

+\input keymod.tex

 \input langcodes.tex
 \input stockitems.tex
 \input langcodes.tex
 \input stockitems.tex

diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex
index 584d5aec4547a6e0a3d3cc5bb489df532e3b1360..01a3ac89f2ea959da03f2d51bd5bb0e80dfc774c 100644 (file)
--- a/docs/latex/wx/keyevent.tex
+++ b/docs/latex/wx/keyevent.tex
@@ -83,6 +83,9 @@ functions that take a wxKeyEvent argument.
 
 \member{bool}{m\_altDown}
 
 
 \member{bool}{m\_altDown}
 

+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+

 true if the Alt key is pressed down.
 
 
 true if the Alt key is pressed down.
 
 


@@ -90,6 +93,9 @@ true if the Alt key is pressed down.
 
 \member{bool}{m\_controlDown}
 
 
 \member{bool}{m\_controlDown}
 

+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+

 true if control is pressed down.
 
 
 true if control is pressed down.
 
 


@@ -97,6 +103,9 @@ true if control is pressed down.
 
 \member{long}{m\_keyCode}
 
 
 \member{long}{m\_keyCode}
 

+\textbf{Deprecated: } Please use \helpref{GetKeyCode}{wxkeyeventgetkeycode}
+instead!
+

 Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers.
 
 
 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}
 
 
 \member{bool}{m\_metaDown}
 

+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+

 true if the Meta key is pressed down.
 
 
 true if the Meta key is pressed down.
 
 


@@ -111,6 +123,9 @@ true if the Meta key is pressed down.
 
 \member{bool}{m\_shiftDown}
 
 
 \member{bool}{m\_shiftDown}
 

+\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers}
+instead!
+

 true if shift is pressed down.
 
 
 true if shift is pressed down.
 
 


@@ -118,6 +133,8 @@ true if shift is pressed down.
 
 \member{int}{m\_x}
 
 
 \member{int}{m\_x}
 

+\textbf{Deprecated: } Please use \helpref{GetX}{wxkeyeventgetx} instead!
+

 X position of the event.
 
 
 X position of the event.
 
 


@@ -125,6 +142,8 @@ X position of the event.
 
 \member{int}{m\_y}
 
 
 \member{int}{m\_y}
 

+\textbf{Deprecated: } Please use \helpref{GetY}{wxkeyeventgety} instead!
+

 Y position of the event.
 
 
 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.
 
 
 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}
 
 
 \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
-but the special "Apple" (a.k.a as "Command") key under Macs: it makes often
-sense to use it instead of, say, ControlDown() because Cmd key is used for the
-same thing under Mac as Ctrl elsewhere (but Ctrl still exists, just not used
-for this purpose under Mac). So for non-Mac platforms this is the same as 
-\helpref{ControlDown()}{wxkeyeventcontroldown} and under Mac this is the same
-as \helpref{MetaDown()}{wxkeyeventmetadown}.
+\textsc{Cmd} is a pseudo key which is the same as Control for PC and Unix
+platforms but the special \textsc{Apple} (a.k.a as \textsc{Command}) key under
+Macs: it makes often sense to use it instead of, say, ControlDown() because Cmd
+key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still
+exists, just not used for this purpose under Mac). So for non-Mac platforms
+this is the same as \helpref{ControlDown()}{wxkeyeventcontroldown} and under
+Mac this is the same as \helpref{MetaDown()}{wxkeyeventmetadown}.

 
 
 \membersection{wxKeyEvent::ControlDown}\label{wxkeyeventcontroldown}
 
 
 \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.
 
 
 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}
 
 
 \membersection{wxKeyEvent::GetKeyCode}\label{wxkeyeventgetkeycode}
 


@@ -177,6 +202,36 @@ charset. You can obtain the corresponding Unicode character using
 \helpref{GetUnicodeKey}{wxkeyeventgetunicodekey}.
 
 
 \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}
 \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.
 
 
 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}
 
 
 \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.
 
 
 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.
+

diff --git a/docs/latex/wx/keymod.tex b/docs/latex/wx/keymod.tex
new file mode 100644 (file)
index 0000000..245039d
--- /dev/null
+++ b/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.
+

diff --git a/include/wx/defs.h b/include/wx/defs.h
index 9c7e9dfb35fdccaa2609e851cdda35b3cdd4383c..38f99915107517408884e782288b99e1360e5f98 100644 (file)
--- a/include/wx/defs.h
+++ b/include/wx/defs.h
@@ -2150,16 +2150,23 @@ enum wxKeyCode
     WXK_SPECIAL20
 };
 
     WXK_SPECIAL20
 };
 

-#if wxUSE_HOTKEY
-enum wxHotkeyModifier
+/* This enum contains bit mask constants used in wxKeyEvent */
+enum wxKeyModifier

 {
 {

-    wxMOD_NONE = 0,
-    wxMOD_ALT = 1,
-    wxMOD_CONTROL = 2,
-    wxMOD_SHIFT = 4,
-    wxMOD_WIN = 8
-};
+    wxMOD_NONE      = 0x0000,
+    wxMOD_ALT       = 0x0001,
+    wxMOD_CONTROL   = 0x0002,
+    wxMOD_ALTGR     = wxMOD_ALT | wxMOD_CONTROL,
+    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
 #endif

+    wxMOD_ALL       = 0xffff
+};

 
 /*  Mapping modes (same values as used by Windows, don't change) */
 enum
 
 /*  Mapping modes (same values as used by Windows, don't change) */
 enum

diff --git a/include/wx/event.h b/include/wx/event.h
index 0fe7a0535b3a1f4a90cb2119a0cf08905b7faceb..54ac43c70dbca46375e37393a7a74a93bbd1df01 100644 (file)
--- a/include/wx/event.h
+++ b/include/wx/event.h
@@ -935,11 +935,22 @@ public:
     wxKeyEvent(wxEventType keyType = wxEVT_NULL);
     wxKeyEvent(const wxKeyEvent& evt);
 
     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; }
     // 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 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
 
     // "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;
 
 
     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;
     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
     bool          m_scanCode;
 
 #if wxUSE_UNICODE