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 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 #include <iosfwd>
18 #include <vector>
19 
20 namespace gui2
21 {
22 class window;
23 
24 namespace event
25 {
26 class dispatcher;
27 
28 class manager
29 {
30 public:
31  manager();
32  ~manager();
33 };
34 
35 /**
36  * The event send to the dispatcher.
37  *
38  * Events prefixed by SDL are (semi)-real SDL events. The handler does some
39  * minor decoding like splitting the button down event to the proper event but
40  * nothing more. Events without an SDL prefix are generated by another signal
41  * eg the windows signal handler for SDL_MOUSE_MOTION can generate a
42  * MOUSE_ENTER, MOUSE_MOTION and MOUSE_LEAVE event and send that to it's
43  * children.
44  *
45  * @note When adding a new entry to the enum also add a unit test.
46  */
47 enum ui_event {
48  SDL_ACTIVATE, /**< The main application window is activated. */
49  DRAW, /**< Periodic redraw request. */
50  CLOSE_WINDOW, /**< A request to close the current window. */
51  SDL_VIDEO_RESIZE, /**< An SDL resize request, coordinate is the new window size. */
52 
53  SDL_MOUSE_MOTION, /**< An SDL mouse motion event. */
54  MOUSE_ENTER, /**< A mouse enter event for a widget. */
55  MOUSE_MOTION, /**< A mouse motion event for a widget. */
56  MOUSE_LEAVE, /**< A mouse leave event for a widget. */
57 
58  SDL_LEFT_BUTTON_DOWN, /**< An SDL left mouse button down event. */
59  SDL_LEFT_BUTTON_UP, /**< An SDL left mouse button up event. */
60  LEFT_BUTTON_DOWN, /**< A left mouse button down event for a widget. */
61  LEFT_BUTTON_UP, /**< A left mouse button up event for a widget. */
62  LEFT_BUTTON_CLICK, /**< A left mouse button click event for a widget. */
63  LEFT_BUTTON_DOUBLE_CLICK, /**< A left mouse button double click event for a widget. */
64 
65  SDL_MIDDLE_BUTTON_DOWN, /**< An SDL middle mouse button down event. */
66  SDL_MIDDLE_BUTTON_UP, /**< An SDL middle mouse button up event. */
67  MIDDLE_BUTTON_DOWN, /**< See LEFT_BUTTON_DOWN. */
68  MIDDLE_BUTTON_UP, /**< See LEFT_BUTTON_UP. */
69  MIDDLE_BUTTON_CLICK, /**< See LEFT_BUTTON_CLICK. */
70  MIDDLE_BUTTON_DOUBLE_CLICK, /**< See LEFT_BUTTON_DOUBLE_CLICK. */
71 
72  SDL_RIGHT_BUTTON_DOWN, /**< An SDL right mouse button down event. */
73  SDL_RIGHT_BUTTON_UP, /**< An SDL right mouse button up event. */
74  RIGHT_BUTTON_DOWN, /**< See LEFT_BUTTON_DOWN. */
75  RIGHT_BUTTON_UP, /**< See LEFT_BUTTON_UP. */
76  RIGHT_BUTTON_CLICK, /**< See LEFT_BUTTON_CLICK. */
77  RIGHT_BUTTON_DOUBLE_CLICK, /**< See LEFT_BUTTON_DOUBLE_CLICK. */
78 
79  SDL_WHEEL_LEFT, /**< An SDL wheel left event. */
80  SDL_WHEEL_RIGHT, /**< An SDL wheel right event. */
81  SDL_WHEEL_UP, /**< An SDL wheel up event. */
82  SDL_WHEEL_DOWN, /**< An SDL wheel down event. */
83  SDL_KEY_DOWN, /**< An SDL key down event. */
84  SDL_TEXT_INPUT, /**< An SDL text input (commit) event. */
85  SDL_TEXT_EDITING, /**< An SDL text editing (IME) event. */
86 
87  NOTIFY_REMOVAL, /**< Sent by a widget to notify others it's being destroyed. */
89  * Sent by a widget to notify others its contents or state are modified.
90  *
91  * What modified means is documented per widget. If not documented the request
92  * means nothing.
93  */
95  * Request to place the widget. This may also trigger an update of other
96  * layout components.
97  */
98 
99  RECEIVE_KEYBOARD_FOCUS, /**< Widget gains keyboard focus. */
100  LOSE_KEYBOARD_FOCUS, /**< Widget loses keyboard focus. */
101 
102  SHOW_TOOLTIP, /**< Request the widget to show its hover tooltip. */
103  NOTIFY_REMOVE_TOOLTIP, /**< Request the widget to remove its hover tooltip. */
104  MESSAGE_SHOW_TOOLTIP, /**< Request to show a tooltip based on the data sent. */
105  SHOW_HELPTIP, /**< Request the widget to show its hover helptip. */
106  MESSAGE_SHOW_HELPTIP, /**< Request to show a helptip based on the data sent. */
107 
111 
112  SDL_RAW_EVENT /**< Raw SDL event. */
113 };
114 
115 /**
116  * Connects a dispatcher to the event handler.
117  *
118  * @param dispatcher The dispatcher to connect.
119  */
121 
122 /**
123  * Disconnects a dispatcher to the event handler.
124  *
125  * @param dispatcher The dispatcher to disconnect.
126  */
128 
129 /**
130  * Gets all event dispatchers in the Z order.
131  */
132 std::vector<dispatcher*>& get_all_dispatchers();
133 
134 /**
135  * Initializes the location of the mouse.
136  *
137  * After a layout of the window the mouse location needs to be updated to
138  * test whether it entered or left a widget. Also after closing a window it's
139  * needed to send a dummy mouse move.
140  */
141 void init_mouse_location();
142 
143 /**
144  * Captures the mouse.
145  *
146  * A dispatcher can capture the mouse, when for example it's pressed on a
147  * button, this means all mouse events after that are send to that widget.
148  *
149  * @param dispatcher The dispatcher which should get the mouse
150  * focus.
151  */
153 
154 /**
155  * Releases a captured mouse.
156  *
157  * @param dispatcher The dispatcher which should release the mouse
158  * capture.
159  */
161 
162 /**
163  * Captures the keyboard.
164  *
165  * A dispatcher can capture the keyboard, when for example it's pressed on a
166  * button, this means all keyboard events after that are send to that widget.
167  *
168  * @param dispatcher The dispatcher which should get the keyboard
169  * focus.
170  */
172 
173 std::ostream& operator<<(std::ostream& stream, const ui_event event);
174 
175 } // namespace event
176 
177 /**
178  * Keeps track of any open windows of any type (modal, non-modal, or tooltip) in the
179  * order in which they were opened. Currently only used as a helper for is_in_dialog(),
180  * but could potentially be useful for other things in the future.
181  */
182 extern std::vector<window*> open_window_stack;
183 
184 /** Removes a entry from the open_window_stack list. This should be used instead of pop_back. */
186 
187 /**
188  * Is a dialog open?
189  *
190  * @note added as backwards compatibility for gui::is_in_dialog.
191  */
192 bool is_in_dialog();
193 
194 } // namespace gui2
Request the widget to show its hover helptip.
Definition: handler.hpp:105
An SDL text editing (IME) event.
Definition: handler.hpp:85
A left mouse button down event for a widget.
Definition: handler.hpp:60
Widget loses keyboard focus.
Definition: handler.hpp:100
An SDL wheel right event.
Definition: handler.hpp:80
Base class for event handling.
Definition: dispatcher.hpp:281
See LEFT_BUTTON_CLICK.
Definition: handler.hpp:76
An SDL left mouse button down event.
Definition: handler.hpp:58
An SDL resize request, coordinate is the new window size.
Definition: handler.hpp:51
An SDL key down event.
Definition: handler.hpp:83
A mouse leave event for a widget.
Definition: handler.hpp:56
bool is_in_dialog()
Is a dialog open?
Definition: handler.cpp:977
See LEFT_BUTTON_DOUBLE_CLICK.
Definition: handler.hpp:77
See LEFT_BUTTON_CLICK.
Definition: handler.hpp:69
void capture_mouse(dispatcher *dispatcher)
Captures the mouse.
Definition: handler.cpp:788
An SDL right mouse button down event.
Definition: handler.hpp:72
void capture_keyboard(dispatcher *dispatcher)
Captures the keyboard.
Definition: handler.cpp:804
See LEFT_BUTTON_DOWN.
Definition: handler.hpp:67
Request to show a helptip based on the data sent.
Definition: handler.hpp:106
An SDL wheel down event.
Definition: handler.hpp:82
See LEFT_BUTTON_UP.
Definition: handler.hpp:75
Widget gains keyboard focus.
Definition: handler.hpp:99
Request the widget to show its hover tooltip.
Definition: handler.hpp:102
void init_mouse_location()
Initializes the location of the mouse.
Definition: handler.cpp:775
Generic file dialog.
Definition: field-fwd.hpp:22
Sent by a widget to notify others its contents or state are modified.
Definition: handler.hpp:88
Request the widget to remove its hover tooltip.
Definition: handler.hpp:103
Request to place the widget.
Definition: handler.hpp:94
A left mouse button up event for a widget.
Definition: handler.hpp:61
Periodic redraw request.
Definition: handler.hpp:49
Sent by a widget to notify others it&#39;s being destroyed.
Definition: handler.hpp:87
std::vector< dispatcher * > & get_all_dispatchers()
Gets all event dispatchers in the Z order.
Definition: handler.cpp:769
void remove_from_window_stack(window *window)
Removes a entry from the open_window_stack list.
Definition: handler.cpp:967
void disconnect_dispatcher(dispatcher *dispatcher)
Disconnects a dispatcher to the event handler.
Definition: handler.cpp:762
An SDL middle mouse button down event.
Definition: handler.hpp:65
void connect_dispatcher(dispatcher *dispatcher)
Connects a dispatcher to the event handler.
Definition: handler.cpp:755
An SDL wheel up event.
Definition: handler.hpp:81
An SDL middle mouse button up event.
Definition: handler.hpp:66
An SDL wheel left event.
Definition: handler.hpp:79
A mouse motion event for a widget.
Definition: handler.hpp:55
A left mouse button double click event for a widget.
Definition: handler.hpp:63
A mouse enter event for a widget.
Definition: handler.hpp:54
std::ostream & operator<<(std::ostream &stream, const ui_event event)
Definition: handler.cpp:813
Request to show a tooltip based on the data sent.
Definition: handler.hpp:104
The main application window is activated.
Definition: handler.hpp:48
An SDL left mouse button up event.
Definition: handler.hpp:59
An SDL text input (commit) event.
Definition: handler.hpp:84
void release_mouse(dispatcher *dispatcher)
Releases a captured mouse.
Definition: handler.cpp:795
See LEFT_BUTTON_DOWN.
Definition: handler.hpp:74
A request to close the current window.
Definition: handler.hpp:50
An SDL right mouse button up event.
Definition: handler.hpp:73
See LEFT_BUTTON_DOUBLE_CLICK.
Definition: handler.hpp:70
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:62
See LEFT_BUTTON_UP.
Definition: handler.hpp:68
ui_event
The event send to the dispatcher.
Definition: handler.hpp:47
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:965
An SDL mouse motion event.
Definition: handler.hpp:53