The Battle for Wesnoth  1.15.0-dev
handler.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2018 by Mark de Wever <koraq@xs4all.nl>
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 #pragma once
16 
17 #ifdef BOOST_MPL_LIMIT_SET_SIZE
18 #undef BOOST_MPL_LIMIT_SET_SIZE
19 #endif
20 #define BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS
21 #define BOOST_MPL_LIMIT_SET_SIZE 30
22 
23 #include <boost/mpl/set.hpp>
24 
25 #include <iosfwd>
26 #include <vector>
27 
28 namespace gui2
29 {
30 class window;
31 
32 namespace event
33 {
34 class dispatcher;
35 
36 class manager
37 {
38 public:
39  manager();
40  ~manager();
41 };
42 
43 /**
44  * The event send to the dispatcher.
45  *
46  * Events prefixed by SDL are (semi)-real SDL events. The handler does some
47  * minor decoding like splitting the button down event to the proper event but
48  * nothing more. Events without an SDL prefix are generated by another signal
49  * eg the windows signal handler for SDL_MOUSE_MOTION can generate a
50  * MOUSE_ENTER, MOUSE_MOTION and MOUSE_LEAVE event and send that to it's
51  * children.
52  *
53  * @note When adding a new entry to the enum also add a unit test.
54  */
55 enum ui_event {
56  SDL_ACTIVATE, /**< The main application window is activated. */
57  DRAW, /**< Periodic redraw request. */
58  CLOSE_WINDOW, /**< A request to close the current window. */
59  SDL_VIDEO_RESIZE, /**< An SDL resize request, coordinate is the new window size. */
60 
61  SDL_MOUSE_MOTION, /**< An SDL mouse motion event. */
62  MOUSE_ENTER, /**< A mouse enter event for a widget. */
63  MOUSE_MOTION, /**< A mouse motion event for a widget. */
64  MOUSE_LEAVE, /**< A mouse leave event for a widget. */
65 
66  SDL_LEFT_BUTTON_DOWN, /**< An SDL left mouse button down event. */
67  SDL_LEFT_BUTTON_UP, /**< An SDL left mouse button up event. */
68  LEFT_BUTTON_DOWN, /**< A left mouse button down event for a widget. */
69  LEFT_BUTTON_UP, /**< A left mouse button up event for a widget. */
70  LEFT_BUTTON_CLICK, /**< A left mouse button click event for a widget. */
71  LEFT_BUTTON_DOUBLE_CLICK, /**< A left mouse button double click event for a widget. */
72 
73  SDL_MIDDLE_BUTTON_DOWN, /**< An SDL middle mouse button down event. */
74  SDL_MIDDLE_BUTTON_UP, /**< An SDL middle mouse button up event. */
75  MIDDLE_BUTTON_DOWN, /**< See LEFT_BUTTON_DOWN. */
76  MIDDLE_BUTTON_UP, /**< See LEFT_BUTTON_UP. */
77  MIDDLE_BUTTON_CLICK, /**< See LEFT_BUTTON_CLICK. */
78  MIDDLE_BUTTON_DOUBLE_CLICK, /**< See LEFT_BUTTON_DOUBLE_CLICK. */
79 
80  SDL_RIGHT_BUTTON_DOWN, /**< An SDL right mouse button down event. */
81  SDL_RIGHT_BUTTON_UP, /**< An SDL right mouse button up event. */
82  RIGHT_BUTTON_DOWN, /**< See LEFT_BUTTON_DOWN. */
83  RIGHT_BUTTON_UP, /**< See LEFT_BUTTON_UP. */
84  RIGHT_BUTTON_CLICK, /**< See LEFT_BUTTON_CLICK. */
85  RIGHT_BUTTON_DOUBLE_CLICK, /**< See LEFT_BUTTON_DOUBLE_CLICK. */
86 
87  SDL_WHEEL_LEFT, /**< An SDL wheel left event. */
88  SDL_WHEEL_RIGHT, /**< An SDL wheel right event. */
89  SDL_WHEEL_UP, /**< An SDL wheel up event. */
90  SDL_WHEEL_DOWN, /**< An SDL wheel down event. */
91  SDL_KEY_DOWN, /**< An SDL key down event. */
92  SDL_TEXT_INPUT, /**< An SDL text input (commit) event. */
93  SDL_TEXT_EDITING, /**< An SDL text editing (IME) event. */
94 
95  NOTIFY_REMOVAL, /**< Sent by a widget to notify others it's being destroyed. */
97  * Sent by a widget to notify others its contents or state are modified.
98  *
99  * What modified means is documented per widget. If not documented the request
100  * means nothing.
101  */
103  * Request to place the widget. This may also trigger an update of other
104  * layout components.
105  */
106 
107  RECEIVE_KEYBOARD_FOCUS, /**< Widget gains keyboard focus. */
108  LOSE_KEYBOARD_FOCUS, /**< Widget loses keyboard focus. */
109 
110  SHOW_TOOLTIP, /**< Request the widget to show its hover tooltip. */
111  NOTIFY_REMOVE_TOOLTIP, /**< Request the widget to remove its hover tooltip. */
112  MESSAGE_SHOW_TOOLTIP, /**< Request to show a tooltip based on the data sent. */
113  SHOW_HELPTIP, /**< Request the widget to show its hover helptip. */
114  MESSAGE_SHOW_HELPTIP, /**< Request to show a helptip based on the data sent. */
115 
120 
121  SDL_RAW_EVENT /**< Raw SDL event. */
122 };
123 
124 /**
125  * Helper for catching use error of dispatcher::connect_signal.
126  *
127  * This helper is needed as a user can't supply the wrong kind of callback
128  * functions to dispatcher::connect_signal. If a wrong callback would be send
129  * it will never get called.
130  *
131  * This version is for callbacks without extra parameters.
132  * NOTE some mouse functions like MOUSE_ENTER don't send the mouse coordinates
133  * to the callback function so they are also in this category.
134  */
135 typedef boost::mpl::set<boost::mpl::int_<DRAW>,
136  boost::mpl::int_<CLOSE_WINDOW>,
137  boost::mpl::int_<MOUSE_ENTER>,
138  boost::mpl::int_<MOUSE_LEAVE>,
139  boost::mpl::int_<LEFT_BUTTON_DOWN>,
140  boost::mpl::int_<LEFT_BUTTON_UP>,
141  boost::mpl::int_<LEFT_BUTTON_CLICK>,
142  boost::mpl::int_<LEFT_BUTTON_DOUBLE_CLICK>,
143  boost::mpl::int_<MIDDLE_BUTTON_DOWN>,
144  boost::mpl::int_<MIDDLE_BUTTON_UP>,
145  boost::mpl::int_<MIDDLE_BUTTON_CLICK>,
146  boost::mpl::int_<MIDDLE_BUTTON_DOUBLE_CLICK>,
147  boost::mpl::int_<RIGHT_BUTTON_DOWN>,
148  boost::mpl::int_<RIGHT_BUTTON_UP>,
149  boost::mpl::int_<RIGHT_BUTTON_CLICK>,
150  boost::mpl::int_<RIGHT_BUTTON_DOUBLE_CLICK>>
152 
153 /**
154  * Helper for catching use error of dispatcher::connect_signal.
155  *
156  * This version is for callbacks with a coordinate as extra parameter.
157  */
158 typedef boost::mpl::set<boost::mpl::int_<SDL_VIDEO_RESIZE>,
159  boost::mpl::int_<SDL_MOUSE_MOTION>,
160  boost::mpl::int_<MOUSE_MOTION>,
161  boost::mpl::int_<SDL_LEFT_BUTTON_DOWN>,
162  boost::mpl::int_<SDL_LEFT_BUTTON_UP>,
163  boost::mpl::int_<SDL_MIDDLE_BUTTON_DOWN>,
164  boost::mpl::int_<SDL_MIDDLE_BUTTON_UP>,
165  boost::mpl::int_<SDL_RIGHT_BUTTON_DOWN>,
166  boost::mpl::int_<SDL_RIGHT_BUTTON_UP>,
167  boost::mpl::int_<SHOW_TOOLTIP>,
168  boost::mpl::int_<SHOW_HELPTIP>,
169  boost::mpl::int_<SDL_WHEEL_UP>,
170  boost::mpl::int_<SDL_WHEEL_DOWN>,
171  boost::mpl::int_<SDL_WHEEL_LEFT>,
172  boost::mpl::int_<SDL_WHEEL_RIGHT>,
173  boost::mpl::int_<SDL_TOUCH_UP>,
174  boost::mpl::int_<SDL_TOUCH_DOWN>> set_event_mouse;
175 
176 /**
177  * Helper for catching use error of dispatcher::connect_signal.
178  *
179  * This version is for callbacks with the keyboard values (these haven't been
180  * determined yet).
181  */
182 typedef boost::mpl::set<boost::mpl::int_<SDL_KEY_DOWN>> set_event_keyboard;
183 
184 /**
185  * Helper for catching use error of dispatcher::connect_signal.
186  *
187  * This version is for callbacks of touch motion events.
188  */
189 typedef boost::mpl::set<boost::mpl::int_<SDL_TOUCH_MOTION>>
191 
192 /**
193  * Helper for catching use error of dispatcher::connect_signal.
194  *
195  * This version is for callbacks of touch gestures events.
196  */
197 typedef boost::mpl::set<boost::mpl::int_<SDL_TOUCH_MULTI_GESTURE>>
199 
200 /**
201  * Helper for catching use error of dispatcher::connect_signal.
202  *
203  * This version is for callbacks with a sender aka notification messages. Like
204  *the
205  * ones in set_event it has no extra parameters, but this version is only
206  * send to the target and not using the pre and post queue.
207  */
208 typedef boost::mpl::set<boost::mpl::int_<NOTIFY_REMOVAL>,
209  boost::mpl::int_<NOTIFY_MODIFIED>,
210  boost::mpl::int_<RECEIVE_KEYBOARD_FOCUS>,
211  boost::mpl::int_<LOSE_KEYBOARD_FOCUS>,
212  boost::mpl::int_<NOTIFY_REMOVE_TOOLTIP>,
213  boost::mpl::int_<SDL_ACTIVATE>>
215 
216 /**
217  * Helper for catching use error of dispatcher::connect_signal.
218  *
219  * This version is for callbacks with a sender aka notification messages.
220  * Unlike the notifications this message is send through the chain. The event
221  * is send from a widget all the way up to the window, who always is the
222  * receiver of the message (unless somebody grabbed it before).
223  */
224 typedef boost::mpl::set<boost::mpl::int_<MESSAGE_SHOW_TOOLTIP>,
225  boost::mpl::int_<MESSAGE_SHOW_HELPTIP>,
226  boost::mpl::int_<REQUEST_PLACEMENT>>
228 
229 /**
230  * Helper for catching use error of dispatcher::connect_signal.
231  *
232  * This version is for callbacks of raw events.
233  */
234 typedef boost::mpl::set<boost::mpl::int_<SDL_RAW_EVENT>> set_event_raw_event;
235 
236 /**
237  * Helper for catching use error of dispatcher::connect_signal.
238  *
239  * This version is for callbacks of text input events.
240  */
241 typedef boost::mpl::set<boost::mpl::int_<SDL_TEXT_INPUT>,
242  boost::mpl::int_<SDL_TEXT_EDITING>>
244 
245 /**
246  * Connects a dispatcher to the event handler.
247  *
248  * @param dispatcher The dispatcher to connect.
249  */
251 
252 /**
253  * Disconnects a dispatcher to the event handler.
254  *
255  * @param dispatcher The dispatcher to disconnect.
256  */
258 
259 /**
260  * Gets all event dispatchers in the Z order.
261  */
262 std::vector<dispatcher*>& get_all_dispatchers();
263 
264 /**
265  * Initializes the location of the mouse.
266  *
267  * After a layout of the window the mouse location needs to be updated to
268  * test whether it entered or left a widget. Also after closing a window it's
269  * needed to send a dummy mouse move.
270  */
271 void init_mouse_location();
272 
273 /**
274  * Captures the mouse.
275  *
276  * A dispatcher can capture the mouse, when for example it's pressed on a
277  * button, this means all mouse events after that are send to that widget.
278  *
279  * @param dispatcher The dispatcher which should get the mouse
280  * focus.
281  */
283 
284 /**
285  * Releases a captured mouse.
286  *
287  * @param dispatcher The dispatcher which should release the mouse
288  * capture.
289  */
291 
292 /**
293  * Captures the keyboard.
294  *
295  * A dispatcher can capture the keyboard, when for example it's pressed on a
296  * button, this means all keyboard events after that are send to that widget.
297  *
298  * @param dispatcher The dispatcher which should get the keyboard
299  * focus.
300  */
302 
303 std::ostream& operator<<(std::ostream& stream, const ui_event event);
304 
305 } // namespace event
306 
307 /**
308  * Keeps track of any open windows of any type (modal, non-modal, or tooltip) in the
309  * order in which they were opened. Currently only used as a helper for is_in_dialog(),
310  * but could potentially be useful for other things in the future.
311  */
312 extern std::vector<window*> open_window_stack;
313 
314 /** Removes a entry from the open_window_stack list. This should be used instead of pop_back. */
316 
317 /**
318  * Is a dialog open?
319  *
320  * @note added as backwards compatibility for gui::is_in_dialog.
321  */
322 bool is_in_dialog();
323 
324 } // namespace gui2
Request the widget to show its hover helptip.
Definition: handler.hpp:113
An SDL text editing (IME) event.
Definition: handler.hpp:93
boost::mpl::set< boost::mpl::int_< SDL_TOUCH_MULTI_GESTURE > > set_event_touch_gesture
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:198
A left mouse button down event for a widget.
Definition: handler.hpp:68
Widget loses keyboard focus.
Definition: handler.hpp:108
An SDL wheel right event.
Definition: handler.hpp:88
Base class for event handling.
Definition: dispatcher.hpp:172
See LEFT_BUTTON_CLICK.
Definition: handler.hpp:84
boost::mpl::set< boost::mpl::int_< SDL_TOUCH_MOTION > > set_event_touch_motion
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:190
An SDL left mouse button down event.
Definition: handler.hpp:66
An SDL resize request, coordinate is the new window size.
Definition: handler.hpp:59
An SDL key down event.
Definition: handler.hpp:91
A mouse leave event for a widget.
Definition: handler.hpp:64
bool is_in_dialog()
Is a dialog open?
Definition: handler.cpp:1118
boost::mpl::set< boost::mpl::int_< SDL_TEXT_INPUT >, boost::mpl::int_< SDL_TEXT_EDITING > > set_event_text_input
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:243
See LEFT_BUTTON_DOUBLE_CLICK.
Definition: handler.hpp:85
See LEFT_BUTTON_CLICK.
Definition: handler.hpp:77
void capture_mouse(dispatcher *dispatcher)
Captures the mouse.
Definition: handler.cpp:926
An SDL right mouse button down event.
Definition: handler.hpp:80
void capture_keyboard(dispatcher *dispatcher)
Captures the keyboard.
Definition: handler.cpp:942
boost::mpl::set< boost::mpl::int_< MESSAGE_SHOW_TOOLTIP >, boost::mpl::int_< MESSAGE_SHOW_HELPTIP >, boost::mpl::int_< REQUEST_PLACEMENT > > set_event_message
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:227
See LEFT_BUTTON_DOWN.
Definition: handler.hpp:75
Request to show a helptip based on the data sent.
Definition: handler.hpp:114
An SDL wheel down event.
Definition: handler.hpp:90
See LEFT_BUTTON_UP.
Definition: handler.hpp:83
Widget gains keyboard focus.
Definition: handler.hpp:107
Request the widget to show its hover tooltip.
Definition: handler.hpp:110
void init_mouse_location()
Initializes the location of the mouse.
Definition: handler.cpp:913
Generic file dialog.
Definition: field-fwd.hpp:22
Sent by a widget to notify others its contents or state are modified.
Definition: handler.hpp:96
Request the widget to remove its hover tooltip.
Definition: handler.hpp:111
Request to place the widget.
Definition: handler.hpp:102
boost::mpl::set< boost::mpl::int_< NOTIFY_REMOVAL >, boost::mpl::int_< NOTIFY_MODIFIED >, boost::mpl::int_< RECEIVE_KEYBOARD_FOCUS >, boost::mpl::int_< LOSE_KEYBOARD_FOCUS >, boost::mpl::int_< NOTIFY_REMOVE_TOOLTIP >, boost::mpl::int_< SDL_ACTIVATE > > set_event_notification
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:214
A left mouse button up event for a widget.
Definition: handler.hpp:69
Periodic redraw request.
Definition: handler.hpp:57
Sent by a widget to notify others it&#39;s being destroyed.
Definition: handler.hpp:95
std::vector< dispatcher * > & get_all_dispatchers()
Gets all event dispatchers in the Z order.
Definition: handler.cpp:907
boost::mpl::set< boost::mpl::int_< SDL_KEY_DOWN > > set_event_keyboard
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:182
void remove_from_window_stack(window *window)
Removes a entry from the open_window_stack list.
Definition: handler.cpp:1108
void disconnect_dispatcher(dispatcher *dispatcher)
Disconnects a dispatcher to the event handler.
Definition: handler.cpp:900
An SDL middle mouse button down event.
Definition: handler.hpp:73
void connect_dispatcher(dispatcher *dispatcher)
Connects a dispatcher to the event handler.
Definition: handler.cpp:893
An SDL wheel up event.
Definition: handler.hpp:89
An SDL middle mouse button up event.
Definition: handler.hpp:74
An SDL wheel left event.
Definition: handler.hpp:87
A mouse motion event for a widget.
Definition: handler.hpp:63
A left mouse button double click event for a widget.
Definition: handler.hpp:71
boost::mpl::set< boost::mpl::int_< DRAW >, boost::mpl::int_< CLOSE_WINDOW >, boost::mpl::int_< MOUSE_ENTER >, boost::mpl::int_< MOUSE_LEAVE >, boost::mpl::int_< LEFT_BUTTON_DOWN >, boost::mpl::int_< LEFT_BUTTON_UP >, boost::mpl::int_< LEFT_BUTTON_CLICK >, boost::mpl::int_< LEFT_BUTTON_DOUBLE_CLICK >, boost::mpl::int_< MIDDLE_BUTTON_DOWN >, boost::mpl::int_< MIDDLE_BUTTON_UP >, boost::mpl::int_< MIDDLE_BUTTON_CLICK >, boost::mpl::int_< MIDDLE_BUTTON_DOUBLE_CLICK >, boost::mpl::int_< RIGHT_BUTTON_DOWN >, boost::mpl::int_< RIGHT_BUTTON_UP >, boost::mpl::int_< RIGHT_BUTTON_CLICK >, boost::mpl::int_< RIGHT_BUTTON_DOUBLE_CLICK > > set_event
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:151
A mouse enter event for a widget.
Definition: handler.hpp:62
std::ostream & operator<<(std::ostream &stream, const ui_event event)
Definition: handler.cpp:951
Request to show a tooltip based on the data sent.
Definition: handler.hpp:112
The main application window is activated.
Definition: handler.hpp:56
An SDL left mouse button up event.
Definition: handler.hpp:67
boost::mpl::set< boost::mpl::int_< SDL_VIDEO_RESIZE >, boost::mpl::int_< SDL_MOUSE_MOTION >, boost::mpl::int_< MOUSE_MOTION >, boost::mpl::int_< SDL_LEFT_BUTTON_DOWN >, boost::mpl::int_< SDL_LEFT_BUTTON_UP >, boost::mpl::int_< SDL_MIDDLE_BUTTON_DOWN >, boost::mpl::int_< SDL_MIDDLE_BUTTON_UP >, boost::mpl::int_< SDL_RIGHT_BUTTON_DOWN >, boost::mpl::int_< SDL_RIGHT_BUTTON_UP >, boost::mpl::int_< SHOW_TOOLTIP >, boost::mpl::int_< SHOW_HELPTIP >, boost::mpl::int_< SDL_WHEEL_UP >, boost::mpl::int_< SDL_WHEEL_DOWN >, boost::mpl::int_< SDL_WHEEL_LEFT >, boost::mpl::int_< SDL_WHEEL_RIGHT >, boost::mpl::int_< SDL_TOUCH_UP >, boost::mpl::int_< SDL_TOUCH_DOWN > > set_event_mouse
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:174
An SDL text input (commit) event.
Definition: handler.hpp:92
boost::mpl::set< boost::mpl::int_< SDL_RAW_EVENT > > set_event_raw_event
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:234
void release_mouse(dispatcher *dispatcher)
Releases a captured mouse.
Definition: handler.cpp:933
See LEFT_BUTTON_DOWN.
Definition: handler.hpp:82
A request to close the current window.
Definition: handler.hpp:58
An SDL right mouse button up event.
Definition: handler.hpp:81
See LEFT_BUTTON_DOUBLE_CLICK.
Definition: handler.hpp:78
base class of top level items, the only item which needs to store the final canvases to draw on ...
Definition: window.hpp:63
A left mouse button click event for a widget.
Definition: handler.hpp:70
See LEFT_BUTTON_UP.
Definition: handler.hpp:76
ui_event
The event send to the dispatcher.
Definition: handler.hpp:55
std::vector< window * > open_window_stack
Keeps track of any open windows of any type (modal, non-modal, or tooltip) in the order in which they...
Definition: handler.cpp:1106
An SDL mouse motion event.
Definition: handler.hpp:61