The Battle for Wesnoth  1.17.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 #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 
112 
113  SDL_RAW_EVENT /**< Raw SDL event. */
114 };
115 
116 /**
117  * Connects a dispatcher to the event handler.
118  *
119  * @param dispatcher The dispatcher to connect.
120  */
122 
123 /**
124  * Disconnects a dispatcher to the event handler.
125  *
126  * @param dispatcher The dispatcher to disconnect.
127  */
129 
130 /**
131  * Gets all event dispatchers in the Z order.
132  */
133 std::vector<dispatcher*>& get_all_dispatchers();
134 
135 /**
136  * Initializes the location of the mouse.
137  *
138  * After a layout of the window the mouse location needs to be updated to
139  * test whether it entered or left a widget. Also after closing a window it's
140  * needed to send a dummy mouse move.
141  */
142 void init_mouse_location();
143 
144 /**
145  * Captures the mouse.
146  *
147  * A dispatcher can capture the mouse, when for example it's pressed on a
148  * button, this means all mouse events after that are send to that widget.
149  *
150  * @param dispatcher The dispatcher which should get the mouse
151  * focus.
152  */
154 
155 /**
156  * Releases a captured mouse.
157  *
158  * @param dispatcher The dispatcher which should release the mouse
159  * capture.
160  */
162 
163 /**
164  * Captures the keyboard.
165  *
166  * A dispatcher can capture the keyboard, when for example it's pressed on a
167  * button, this means all keyboard events after that are send to that widget.
168  *
169  * @param dispatcher The dispatcher which should get the keyboard
170  * focus.
171  */
173 
174 std::ostream& operator<<(std::ostream& stream, const ui_event event);
175 
176 } // namespace event
177 
178 /**
179  * Keeps track of any open windows of any type (modal, non-modal, or tooltip) in the
180  * order in which they were opened. Currently only used as a helper for is_in_dialog(),
181  * but could potentially be useful for other things in the future.
182  */
183 extern std::vector<window*> open_window_stack;
184 
185 /** Removes a entry from the open_window_stack list. This should be used instead of pop_back. */
187 
188 /**
189  * Is a dialog open?
190  *
191  * @note added as backwards compatibility for gui::is_in_dialog.
192  */
193 bool is_in_dialog();
194 
195 } // 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:306
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:1115
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:923
An SDL right mouse button down event.
Definition: handler.hpp:72
void capture_keyboard(dispatcher *dispatcher)
Captures the keyboard.
Definition: handler.cpp:939
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:910
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:904
void remove_from_window_stack(window *window)
Removes a entry from the open_window_stack list.
Definition: handler.cpp:1105
void disconnect_dispatcher(dispatcher *dispatcher)
Disconnects a dispatcher to the event handler.
Definition: handler.cpp:897
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:890
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:948
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:930
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:64
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:1103
An SDL mouse motion event.
Definition: handler.hpp:53