The Battle for Wesnoth  1.13.10+dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
handler.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2017 by Mark de Wever <koraq@xs4all.nl>
3  Part of the Battle for Wesnoth Project http://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 
119 
120  SDL_RAW_EVENT /**< Raw SDL event. */
121 };
122 
123 /**
124  * Helper for catching use error of dispatcher::connect_signal.
125  *
126  * This helper is needed as a user can't supply the wrong kind of callback
127  * functions to dispatcher::connect_signal. If a wrong callback would be send
128  * it will never get called.
129  *
130  * This version is for callbacks without extra parameters.
131  * NOTE some mouse functions like MOUSE_ENTER don't send the mouse coordinates
132  * to the callback function so they are also in this category.
133  */
134 typedef boost::mpl::set<boost::mpl::int_<DRAW>,
135  boost::mpl::int_<CLOSE_WINDOW>,
136  boost::mpl::int_<MOUSE_ENTER>,
137  boost::mpl::int_<MOUSE_LEAVE>,
138  boost::mpl::int_<LEFT_BUTTON_DOWN>,
139  boost::mpl::int_<LEFT_BUTTON_UP>,
140  boost::mpl::int_<LEFT_BUTTON_CLICK>,
141  boost::mpl::int_<LEFT_BUTTON_DOUBLE_CLICK>,
142  boost::mpl::int_<MIDDLE_BUTTON_DOWN>,
143  boost::mpl::int_<MIDDLE_BUTTON_UP>,
144  boost::mpl::int_<MIDDLE_BUTTON_CLICK>,
145  boost::mpl::int_<MIDDLE_BUTTON_DOUBLE_CLICK>,
146  boost::mpl::int_<RIGHT_BUTTON_DOWN>,
147  boost::mpl::int_<RIGHT_BUTTON_UP>,
148  boost::mpl::int_<RIGHT_BUTTON_CLICK>,
149  boost::mpl::int_<RIGHT_BUTTON_DOUBLE_CLICK> >
151 
152 /**
153  * Helper for catching use error of dispatcher::connect_signal.
154  *
155  * This version is for callbacks with a coordinate as extra parameter.
156  */
157 typedef boost::mpl::set<boost::mpl::int_<SDL_VIDEO_RESIZE>,
158  boost::mpl::int_<SDL_MOUSE_MOTION>,
159  boost::mpl::int_<MOUSE_MOTION>,
160  boost::mpl::int_<SDL_LEFT_BUTTON_DOWN>,
161  boost::mpl::int_<SDL_LEFT_BUTTON_UP>,
162  boost::mpl::int_<SDL_MIDDLE_BUTTON_DOWN>,
163  boost::mpl::int_<SDL_MIDDLE_BUTTON_UP>,
164  boost::mpl::int_<SDL_RIGHT_BUTTON_DOWN>,
165  boost::mpl::int_<SDL_RIGHT_BUTTON_UP>,
166  boost::mpl::int_<SHOW_TOOLTIP>,
167  boost::mpl::int_<SHOW_HELPTIP>,
168  boost::mpl::int_<SDL_WHEEL_UP>,
169  boost::mpl::int_<SDL_WHEEL_DOWN>,
170  boost::mpl::int_<SDL_WHEEL_LEFT>,
171  boost::mpl::int_<SDL_WHEEL_RIGHT> > set_event_mouse;
172 
173 /**
174  * Helper for catching use error of dispatcher::connect_signal.
175  *
176  * This version is for callbacks with the keyboard values (these haven't been
177  * determined yet).
178  */
179 typedef boost::mpl::set<boost::mpl::int_<SDL_KEY_DOWN> > set_event_keyboard;
180 
181 /**
182  * Helper for catching use error of dispatcher::connect_signal.
183  *
184  * This version is for callbacks of touch events.
185  */
186 typedef boost::mpl::set<boost::mpl::int_<SDL_TOUCH_MOTION>,
187  boost::mpl::int_<SDL_TOUCH_UP>,
188  boost::mpl::int_<SDL_TOUCH_DOWN> >
190 
191 /**
192  * Helper for catching use error of dispatcher::connect_signal.
193  *
194  * This version is for callbacks with a sender aka notification messages. Like
195  *the
196  * ones in set_event it has no extra parameters, but this version is only
197  * send to the target and not using the pre and post queue.
198  */
199 typedef boost::mpl::set<boost::mpl::int_<NOTIFY_REMOVAL>,
200  boost::mpl::int_<NOTIFY_MODIFIED>,
201  boost::mpl::int_<RECEIVE_KEYBOARD_FOCUS>,
202  boost::mpl::int_<LOSE_KEYBOARD_FOCUS>,
203  boost::mpl::int_<NOTIFY_REMOVE_TOOLTIP>,
204  boost::mpl::int_<SDL_ACTIVATE> >
206 
207 /**
208  * Helper for catching use error of dispatcher::connect_signal.
209  *
210  * This version is for callbacks with a sender aka notification messages.
211  * Unlike the notifications this message is send through the chain. The event
212  * is send from a widget all the way up to the window, who always is the
213  * receiver of the message (unless somebody grabbed it before).
214  */
215 typedef boost::mpl::set<boost::mpl::int_<MESSAGE_SHOW_TOOLTIP>,
216  boost::mpl::int_<MESSAGE_SHOW_HELPTIP>,
217  boost::mpl::int_<REQUEST_PLACEMENT> >
219 
220 /**
221  * Helper for catching use error of dispatcher::connect_signal.
222  *
223  * This version is for callbacks of raw events.
224  */
225 typedef boost::mpl::set<boost::mpl::int_<SDL_RAW_EVENT> > set_event_raw_event;
226 
227 /**
228  * Helper for catching use error of dispatcher::connect_signal.
229  *
230  * This version is for callbacks of text input events.
231  */
232 typedef boost::mpl::set<boost::mpl::int_<SDL_TEXT_INPUT>,
233  boost::mpl::int_<SDL_TEXT_EDITING>>
235 
236 /**
237  * Connects a dispatcher to the event handler.
238  *
239  * @param dispatcher The dispatcher to connect.
240  */
242 
243 /**
244  * Disconnects a dispatcher to the event handler.
245  *
246  * @param dispatcher The dispatcher to disconnect.
247  */
249 
250 /**
251  * Gets all event dispatchers in the Z order.
252  */
253 std::vector<dispatcher*>& get_all_dispatchers();
254 
255 /**
256  * Initializes the location of the mouse.
257  *
258  * After a layout of the window the mouse location needs to be updated to
259  * test whether it entered or left a widget. Also after closing a window it's
260  * needed to send a dummy mouse move.
261  */
262 void init_mouse_location();
263 
264 /**
265  * Captures the mouse.
266  *
267  * A dispatcher can capture the mouse, when for example it's pressed on a
268  * button, this means all mouse events after that are send to that widget.
269  *
270  * @param dispatcher The dispatcher which should get the mouse
271  * focus.
272  */
274 
275 /**
276  * Releases a captured mouse.
277  *
278  * @param dispatcher The dispatcher which should release the mouse
279  * capture.
280  */
282 
283 /**
284  * Captures the keyboard.
285  *
286  * A dispatcher can capture the keyboard, when for example it's pressed on a
287  * button, this means all keyboard events after that are send to that widget.
288  *
289  * @param dispatcher The dispatcher which should get the keyboard
290  * focus.
291  */
293 
294 std::ostream& operator<<(std::ostream& stream, const ui_event event);
295 
296 } // namespace event
297 
298 /**
299  * Keeps track of any open windows of any type (modal, non-modal, or tooltip) in the
300  * order in which they were opened. Currently only used as a helper for is_in_dialog(),
301  * but could potentially be useful for other things in the future.
302  */
303 extern std::vector<window*> open_window_stack;
304 
305 /** Removes a entry from the open_window_stack list. This should be used instead of pop_back. */
307 
308 /**
309  * Is a dialog open?
310  *
311  * @note added as backwards compatibility for gui::is_in_dialog.
312  */
313 bool is_in_dialog();
314 
315 } // namespace gui2
Request the widget to show its hover helptip.
Definition: handler.hpp:113
boost::mpl::set< boost::mpl::int_< SDL_TOUCH_MOTION >, boost::mpl::int_< SDL_TOUCH_UP >, boost::mpl::int_< SDL_TOUCH_DOWN > > set_event_touch
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:189
An SDL text editing (IME) event.
Definition: handler.hpp:93
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:161
See LEFT_BUTTON_CLICK.
Definition: handler.hpp:84
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:1034
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:234
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:845
An SDL right mouse button down event.
Definition: handler.hpp:80
void capture_keyboard(dispatcher *dispatcher)
Captures the keyboard.
Definition: handler.cpp:861
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:218
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:832
Generic file dialog.
Definition: field-fwd.hpp:22
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 > > set_event_mouse
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:171
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:205
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's being destroyed.
Definition: handler.hpp:95
std::vector< dispatcher * > & get_all_dispatchers()
Gets all event dispatchers in the Z order.
Definition: handler.cpp:826
boost::mpl::set< boost::mpl::int_< SDL_KEY_DOWN > > set_event_keyboard
Helper for catching use error of dispatcher::connect_signal.
Definition: handler.hpp:179
void remove_from_window_stack(window *window)
Removes a entry from the open_window_stack list.
Definition: handler.cpp:1024
void disconnect_dispatcher(dispatcher *dispatcher)
Disconnects a dispatcher to the event handler.
Definition: handler.cpp:819
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:812
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:150
A mouse enter event for a widget.
Definition: handler.hpp:62
std::ostream & operator<<(std::ostream &stream, const ui_event event)
Definition: handler.cpp:870
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
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:225
void release_mouse(dispatcher *dispatcher)
Releases a captured mouse.
Definition: handler.cpp:852
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:62
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:1022
An SDL mouse motion event.
Definition: handler.hpp:61