The Battle for Wesnoth  1.17.0-dev
handler.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2021
3  by Mark de Wever <koraq@xs4all.nl>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 #pragma once
17 
18 #include <iosfwd>
19 #include <vector>
20 
21 namespace gui2
22 {
23 class window;
24 
25 namespace event
26 {
27 class dispatcher;
28 
29 class manager
30 {
31 public:
32  manager();
33  ~manager();
34 };
35 
36 /**
37  * The event send to the dispatcher.
38  *
39  * Events prefixed by SDL are (semi)-real SDL events. The handler does some
40  * minor decoding like splitting the button down event to the proper event but
41  * nothing more. Events without an SDL prefix are generated by another signal
42  * eg the windows signal handler for SDL_MOUSE_MOTION can generate a
43  * MOUSE_ENTER, MOUSE_MOTION and MOUSE_LEAVE event and send that to it's
44  * children.
45  *
46  * @note When adding a new entry to the enum also add a unit test.
47  */
48 enum ui_event {
49  SDL_ACTIVATE, /**< The main application window is activated. */
50  DRAW, /**< Periodic redraw request. */
51  CLOSE_WINDOW, /**< A request to close the current window. */
52  SDL_VIDEO_RESIZE, /**< An SDL resize request, coordinate is the new window size. */
53 
54  SDL_MOUSE_MOTION, /**< An SDL mouse motion event. */
55  MOUSE_ENTER, /**< A mouse enter event for a widget. */
56  MOUSE_MOTION, /**< A mouse motion event for a widget. */
57  MOUSE_LEAVE, /**< A mouse leave event for a widget. */
58 
59  SDL_LEFT_BUTTON_DOWN, /**< An SDL left mouse button down event. */
60  SDL_LEFT_BUTTON_UP, /**< An SDL left mouse button up event. */
61  LEFT_BUTTON_DOWN, /**< A left mouse button down event for a widget. */
62  LEFT_BUTTON_UP, /**< A left mouse button up event for a widget. */
63  LEFT_BUTTON_CLICK, /**< A left mouse button click event for a widget. */
64  LEFT_BUTTON_DOUBLE_CLICK, /**< A left mouse button double click event for a widget. */
65 
66  SDL_MIDDLE_BUTTON_DOWN, /**< An SDL middle mouse button down event. */
67  SDL_MIDDLE_BUTTON_UP, /**< An SDL middle mouse button up event. */
68  MIDDLE_BUTTON_DOWN, /**< See LEFT_BUTTON_DOWN. */
69  MIDDLE_BUTTON_UP, /**< See LEFT_BUTTON_UP. */
70  MIDDLE_BUTTON_CLICK, /**< See LEFT_BUTTON_CLICK. */
71  MIDDLE_BUTTON_DOUBLE_CLICK, /**< See LEFT_BUTTON_DOUBLE_CLICK. */
72 
73  SDL_RIGHT_BUTTON_DOWN, /**< An SDL right mouse button down event. */
74  SDL_RIGHT_BUTTON_UP, /**< An SDL right mouse button up event. */
75  RIGHT_BUTTON_DOWN, /**< See LEFT_BUTTON_DOWN. */
76  RIGHT_BUTTON_UP, /**< See LEFT_BUTTON_UP. */
77  RIGHT_BUTTON_CLICK, /**< See LEFT_BUTTON_CLICK. */
78  RIGHT_BUTTON_DOUBLE_CLICK, /**< See LEFT_BUTTON_DOUBLE_CLICK. */
79 
80  SDL_WHEEL_LEFT, /**< An SDL wheel left event. */
81  SDL_WHEEL_RIGHT, /**< An SDL wheel right event. */
82  SDL_WHEEL_UP, /**< An SDL wheel up event. */
83  SDL_WHEEL_DOWN, /**< An SDL wheel down event. */
84  SDL_KEY_DOWN, /**< An SDL key down event. */
85  SDL_TEXT_INPUT, /**< An SDL text input (commit) event. */
86  SDL_TEXT_EDITING, /**< An SDL text editing (IME) event. */
87 
88  NOTIFY_REMOVAL, /**< Sent by a widget to notify others it's being destroyed. */
90  * Sent by a widget to notify others its contents or state are modified.
91  *
92  * What modified means is documented per widget. If not documented the request
93  * means nothing.
94  */
96  * Request to place the widget. This may also trigger an update of other
97  * layout components.
98  */
99 
100  RECEIVE_KEYBOARD_FOCUS, /**< Widget gains keyboard focus. */
101  LOSE_KEYBOARD_FOCUS, /**< Widget loses keyboard focus. */
102 
103  SHOW_TOOLTIP, /**< Request the widget to show its hover tooltip. */
104  NOTIFY_REMOVE_TOOLTIP, /**< Request the widget to remove its hover tooltip. */
105  MESSAGE_SHOW_TOOLTIP, /**< Request to show a tooltip based on the data sent. */
106  SHOW_HELPTIP, /**< Request the widget to show its hover helptip. */
107  MESSAGE_SHOW_HELPTIP, /**< Request to show a helptip based on the data sent. */
108 
113 
114  SDL_RAW_EVENT /**< Raw SDL event. */
115 };
116 
117 /**
118  * Connects a dispatcher to the event handler.
119  *
120  * @param dispatcher The dispatcher to connect.
121  */
123 
124 /**
125  * Disconnects a dispatcher to the event handler.
126  *
127  * @param dispatcher The dispatcher to disconnect.
128  */
130 
131 /**
132  * Gets all event dispatchers in the Z order.
133  */
134 std::vector<dispatcher*>& get_all_dispatchers();
135 
136 /**
137  * Initializes the location of the mouse.
138  *
139  * After a layout of the window the mouse location needs to be updated to
140  * test whether it entered or left a widget. Also after closing a window it's
141  * needed to send a dummy mouse move.
142  */
143 void init_mouse_location();
144 
145 /**
146  * Captures the mouse.
147  *
148  * A dispatcher can capture the mouse, when for example it's pressed on a
149  * button, this means all mouse events after that are send to that widget.
150  *
151  * @param dispatcher The dispatcher which should get the mouse
152  * focus.
153  */
155 
156 /**
157  * Releases a captured mouse.
158  *
159  * @param dispatcher The dispatcher which should release the mouse
160  * capture.
161  */
163 
164 /**
165  * Captures the keyboard.
166  *
167  * A dispatcher can capture the keyboard, when for example it's pressed on a
168  * button, this means all keyboard events after that are send to that widget.
169  *
170  * @param dispatcher The dispatcher which should get the keyboard
171  * focus.
172  */
174 
175 std::ostream& operator<<(std::ostream& stream, const ui_event event);
176 
177 } // namespace event
178 
179 /**
180  * Keeps track of any open windows of any type (modal, non-modal, or tooltip) in the
181  * order in which they were opened. Currently only used as a helper for is_in_dialog(),
182  * but could potentially be useful for other things in the future.
183  */
184 extern std::vector<window*> open_window_stack;
185 
186 /** Removes a entry from the open_window_stack list. This should be used instead of pop_back. */
188 
189 /**
190  * Is a dialog open?
191  *
192  * @note added as backwards compatibility for gui::is_in_dialog.
193  */
194 bool is_in_dialog();
195 
196 } // namespace gui2
Request the widget to show its hover helptip.
Definition: handler.hpp:106
An SDL text editing (IME) event.
Definition: handler.hpp:86
A left mouse button down event for a widget.
Definition: handler.hpp:61
Widget loses keyboard focus.
Definition: handler.hpp:101
An SDL wheel right event.
Definition: handler.hpp:81
Base class for event handling.
Definition: dispatcher.hpp:307
See LEFT_BUTTON_CLICK.
Definition: handler.hpp:77
An SDL left mouse button down event.
Definition: handler.hpp:59
An SDL resize request, coordinate is the new window size.
Definition: handler.hpp:52
An SDL key down event.
Definition: handler.hpp:84
A mouse leave event for a widget.
Definition: handler.hpp:57
bool is_in_dialog()
Is a dialog open?
Definition: handler.cpp:1116
See LEFT_BUTTON_DOUBLE_CLICK.
Definition: handler.hpp:78
See LEFT_BUTTON_CLICK.
Definition: handler.hpp:70
void capture_mouse(dispatcher *dispatcher)
Captures the mouse.
Definition: handler.cpp:924
An SDL right mouse button down event.
Definition: handler.hpp:73
void capture_keyboard(dispatcher *dispatcher)
Captures the keyboard.
Definition: handler.cpp:940
See LEFT_BUTTON_DOWN.
Definition: handler.hpp:68
Request to show a helptip based on the data sent.
Definition: handler.hpp:107
An SDL wheel down event.
Definition: handler.hpp:83
See LEFT_BUTTON_UP.
Definition: handler.hpp:76
Widget gains keyboard focus.
Definition: handler.hpp:100
Request the widget to show its hover tooltip.
Definition: handler.hpp:103
void init_mouse_location()
Initializes the location of the mouse.
Definition: handler.cpp:911
Generic file dialog.
Definition: field-fwd.hpp:23
Sent by a widget to notify others its contents or state are modified.
Definition: handler.hpp:89
Request the widget to remove its hover tooltip.
Definition: handler.hpp:104
Request to place the widget.
Definition: handler.hpp:95
A left mouse button up event for a widget.
Definition: handler.hpp:62
Periodic redraw request.
Definition: handler.hpp:50
Sent by a widget to notify others it&#39;s being destroyed.
Definition: handler.hpp:88
std::vector< dispatcher * > & get_all_dispatchers()
Gets all event dispatchers in the Z order.
Definition: handler.cpp:905
void remove_from_window_stack(window *window)
Removes a entry from the open_window_stack list.
Definition: handler.cpp:1106
void disconnect_dispatcher(dispatcher *dispatcher)
Disconnects a dispatcher to the event handler.
Definition: handler.cpp:898
An SDL middle mouse button down event.
Definition: handler.hpp:66
void connect_dispatcher(dispatcher *dispatcher)
Connects a dispatcher to the event handler.
Definition: handler.cpp:891
An SDL wheel up event.
Definition: handler.hpp:82
An SDL middle mouse button up event.
Definition: handler.hpp:67
An SDL wheel left event.
Definition: handler.hpp:80
A mouse motion event for a widget.
Definition: handler.hpp:56
A left mouse button double click event for a widget.
Definition: handler.hpp:64
A mouse enter event for a widget.
Definition: handler.hpp:55
std::ostream & operator<<(std::ostream &stream, const ui_event event)
Definition: handler.cpp:949
Request to show a tooltip based on the data sent.
Definition: handler.hpp:105
The main application window is activated.
Definition: handler.hpp:49
An SDL left mouse button up event.
Definition: handler.hpp:60
An SDL text input (commit) event.
Definition: handler.hpp:85
void release_mouse(dispatcher *dispatcher)
Releases a captured mouse.
Definition: handler.cpp:931
See LEFT_BUTTON_DOWN.
Definition: handler.hpp:75
A request to close the current window.
Definition: handler.hpp:51
An SDL right mouse button up event.
Definition: handler.hpp:74
See LEFT_BUTTON_DOUBLE_CLICK.
Definition: handler.hpp:71
base class of top level items, the only item which needs to store the final canvases to draw on...
Definition: window.hpp:65
A left mouse button click event for a widget.
Definition: handler.hpp:63
See LEFT_BUTTON_UP.
Definition: handler.hpp:69
ui_event
The event send to the dispatcher.
Definition: handler.hpp:48
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:1104
An SDL mouse motion event.
Definition: handler.hpp:54