1 // -*- C++ -*-
2 /* GG is a GUI for OpenGL.
3    Copyright (C) 2003-2008 T. Zachary Laine
4 
5    This library is free software; you can redistribute it and/or
6    modify it under the terms of the GNU Lesser General Public License
7    as published by the Free Software Foundation; either version 2.1
8    of the License, or (at your option) any later version.
9 
10    This library is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13    Lesser General Public License for more details.
14 
15    You should have received a copy of the GNU Lesser General Public
16    License along with this library; if not, write to the Free
17    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
18    02111-1307 USA
19 
20    If you do not wish to comply with the terms of the LGPL please
21    contact the author as other terms are available for a fee.
22 
23    Zach Laine
24    whatwasthataddress@gmail.com */
25 
26 /** \file WndEvent.h \brief Contains the WndEvent class, which is used
27     internally by GG to dispatch event messages to Wnds. */
28 
29 #ifndef _GG_WndEvent_h_
30 #define _GG_WndEvent_h_
31 
32 #include <GG/Base.h>
33 #include <GG/Exception.h>
34 #include <GG/Flags.h>
35 
36 #include <map>
37 #include <vector>
38 
39 
40 namespace GG {
41 
42 class Timer;
43 class Wnd;
44 
45 // Adpated from SDLKey enum in SDL_keysym.h of the SDL library.
46 GG_FLAG_TYPE(ModKey);
47 extern GG_API const ModKey MOD_KEY_NONE;         ///< No modifier key.
48 extern GG_API const ModKey MOD_KEY_LSHIFT;       ///< The left Shift key.
49 extern GG_API const ModKey MOD_KEY_RSHIFT;       ///< The right Shift key.
50 extern GG_API const ModKey MOD_KEY_LCTRL;        ///< The left Control key.
51 extern GG_API const ModKey MOD_KEY_RCTRL;        ///< The right Control key.
52 extern GG_API const ModKey MOD_KEY_LALT;         ///< The left Alt key.
53 extern GG_API const ModKey MOD_KEY_RALT;         ///< The right Alt key.
54 extern GG_API const ModKey MOD_KEY_LMETA;        ///< The left Meta key.
55 extern GG_API const ModKey MOD_KEY_RMETA;        ///< The right Meta key.
56 extern GG_API const ModKey MOD_KEY_NUM;          ///< The Num Lock key.
57 extern GG_API const ModKey MOD_KEY_CAPS;         ///< The Caps Lock key.
58 extern GG_API const ModKey MOD_KEY_MODE;         ///< The Mode key.
59 extern GG_API const Flags<ModKey> MOD_KEY_CTRL;  ///< Either Control key.
60 extern GG_API const Flags<ModKey> MOD_KEY_SHIFT; ///< Either Shift key.
61 extern GG_API const Flags<ModKey> MOD_KEY_ALT;   ///< Either Alt key.
62 extern GG_API const Flags<ModKey> MOD_KEY_META;  ///< Either Meta key.
63 
64 /** \brief Encapsulates a Wnd event that is passed from the singleton GUI to a
65     Wnd.
66 
67     The various types of WndEvents correspond to the various message member
68     functions of Wnd, some of which have different parameterizations.  Rather
69     than have a less-efficient but more-easily-extensible hierarchy of
70     WndEvent types, a single WndEvent type exists that has all possible
71     parameters to a Wnd message function call.  Therefore, not all of
72     WndEvent's accessors will return sensical results, depending on the
73     WndEventType of the WndEvent.  Note that Wnd events may be filtered before
74     they actually reach the target Wnd \see Wnd */
75 class GG_API WndEvent
76 {
77 public:
78     /** The types of Wnd events.  Each of these corresponds to a Wnd member
79         function of the same name. */
80     enum EventType : int {
81         LButtonDown,
82         LDrag,
83         LButtonUp,
84         LClick,
85         LDoubleClick,
86         MButtonDown,
87         MDrag,
88         MButtonUp,
89         MClick,
90         MDoubleClick,
91         RButtonDown,
92         RDrag,
93         RButtonUp,
94         RClick,
95         RDoubleClick,
96         MouseEnter,
97         MouseHere,
98         MouseLeave,
99         MouseWheel,
100         DragDropEnter,
101         DragDropHere,
102         CheckDrops,
103         DragDropLeave,
104         DragDroppedOn,
105         KeyPress,
106         KeyRelease,
107         TextInput,
108         GainingFocus,
109         LosingFocus,
110         TimerFiring
111     };
112 
113     /** \name Structors */ ///@{
114     WndEvent(EventType type, const Pt& pt, Flags<ModKey> mod_keys);
115     WndEvent(EventType type, const Pt& pt, const Pt& move, Flags<ModKey> mod_keys);
116     WndEvent(EventType type, const Pt& pt, int move, Flags<ModKey> mod_keys);
117     WndEvent(EventType type, const Pt& pt, const std::vector<std::shared_ptr<Wnd>>& drag_drop_wnds, Flags<ModKey> mod_keys);
118     WndEvent(EventType type, const Pt& pt, const std::map<std::shared_ptr<Wnd>, Pt>& drag_drop_wnds, Flags<ModKey> mod_keys);
119     WndEvent(EventType type, const Pt& pt, const Wnd* const drag_wnd, Flags<ModKey> mod_keys);
120     WndEvent(EventType type, Key key, std::uint32_t code_point, Flags<ModKey> mod_keys);
121     WndEvent(EventType type, unsigned int ticks, Timer* timer);
122     WndEvent(EventType type, const std::string* text);
123     explicit WndEvent(EventType type);
124     //@}
125 
126     /** \name Accessors */ ///@{
127     EventType                   Type() const;           ///< returns the type of the WndEvent
128     const Pt&                   Point() const;          ///< returns the point at which the event took place, if any
129     Key                         GetKey() const;         ///< returns the key pressed or released in the WndEvent, if any
130 
131     /** Returns the Unicode code point for the key pressed or released in the
132         WndEvent, if any.
133 
134         @note  This may be zero, even in a KeyPress or KeyRelease event, if
135         Unicode support is unavailable. */
136     std::uint32_t KeyCodePoint() const;
137 
138     Flags<ModKey>               ModKeys() const;        ///< returns the modifiers to the WndEvent's keypress, if any
139     const Pt&                   DragMove() const;       ///< returns the amount of drag movement represented by the WndEvent, if any
140     int                         WheelMove() const;      ///< returns the ammount of mouse wheel movement represented by the WndEvent, if any
141     unsigned int                Ticks() const;          ///< returns the number of ticks represented by the WndEvent. if any
142     Timer*                      GetTimer() const;       ///< returns the Timer represented by the WndEvent. if any
143     const std::string*          GetText() const;        ///< returns the utf8 text represented by the WndEvent, if any
144     const std::map<const Wnd* const, Pt>&   DragDropWnds() const;   ///< returns the drag-and-drop wnds represented by the WndEvent, if any
145     std::vector<std::shared_ptr<Wnd>>&          GetDragDropWnds() const;
146     std::map<const Wnd*, bool>& GetAcceptableDropWnds() const;
147     //@}
148 
149 private:
150     EventType                       m_type;
151     Pt                              m_point;
152     Key                             m_key{GGK_NONE};
153 
154     std::uint32_t                   m_key_code_point = 0;
155 
156     Flags<ModKey>                   m_mod_keys;
157     Pt                              m_drag_move;
158     int                             m_wheel_move = 0;
159 
160     std::map<const Wnd* const, Pt>  m_drag_drop_wnds;
161 
162     unsigned int                    m_ticks = 0;
163     Timer*                          m_timer = nullptr;
164     const std::string*              m_text = nullptr;
165 
166     mutable std::vector<std::shared_ptr<Wnd>>   m_dropped_wnds;
167     mutable std::map<const Wnd*, bool>          m_acceptable_drop_wnds;
168 };
169 
170 } // namespace GG
171 
172 #endif
173