From e7102772826e7034ae89536dcd018039526293d1 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Thu, 10 Nov 2005 11:59:47 +0000 Subject: [PATCH] added wxKeyEvent::GetModifiers() git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@36148 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/changes.txt | 1 + docs/latex/wx/constant.tex | 1 + docs/latex/wx/keyevent.tex | 75 ++++++++++++++++++++++++++++++++++---- docs/latex/wx/keymod.tex | 34 +++++++++++++++++ include/wx/defs.h | 23 ++++++++---- include/wx/event.h | 16 +++++++- 6 files changed, 134 insertions(+), 16 deletions(-) create mode 100644 docs/latex/wx/keymod.tex diff --git a/docs/changes.txt b/docs/changes.txt index dd89687033..dd3f962412 100644 --- a/docs/changes.txt +++ b/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). diff --git a/docs/latex/wx/constant.tex b/docs/latex/wx/constant.tex index 8eb8452dfa..c70570f0c4 100644 --- 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 keymod.tex \input langcodes.tex \input stockitems.tex diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex index 584d5aec45..01a3ac89f2 100644 --- 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} +\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 -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} @@ -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. + diff --git a/docs/latex/wx/keymod.tex b/docs/latex/wx/keymod.tex new file mode 100644 index 0000000000..245039d2af --- /dev/null +++ b/docs/latex/wx/keymod.tex @@ -0,0 +1,34 @@ +\section{Key Modifiers}\label{keymodifiers} + +\wxheading{Include files} + + + +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 9c7e9dfb35..38f9991510 100644 --- a/include/wx/defs.h +++ b/include/wx/defs.h @@ -2150,16 +2150,23 @@ enum wxKeyCode 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 + wxMOD_ALL = 0xffff +}; /* 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 0fe7a0535b..54ac43c70d 100644 --- a/include/wx/event.h +++ b/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 -- 2.45.2