The Battle for Wesnoth  1.19.0-dev
distributor.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2024
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 /**
19  * @file
20  * Contains the event distributor.
21  *
22  * The event distributor exists of several classes which are combined in one
23  * templated distributor class. The classes are closely tight together.
24  *
25  * All classes have direct access to each others members since they should act
26  * as one. (Since the buttons are a templated subclass it's not possible to use
27  * private subclasses.)
28  *
29  * The mouse_motion class handles the mouse motion and holds the owner of us
30  * since all classes virtually inherit us.
31  *
32  * The mouse_button classes are templated classes per mouse button, the
33  * template parameters are used to make the difference between the mouse
34  * buttons. Although it's easily possible to add more mouse buttons in the
35  * code several places only expect a left, middle and right button.
36  *
37  * distributor is the main class to be used in the user code. This class
38  * contains the handling of the keyboard as well.
39  */
40 
43 #include "sdl/point.hpp"
44 
45 #include <string>
46 #include <vector>
47 
48 namespace gui2
49 {
50 class widget;
51 
52 namespace event
53 {
54 
55 /***** ***** ***** ***** mouse_motion ***** ***** ***** ***** *****/
56 
58 {
59 public:
60  mouse_motion(widget& owner, const dispatcher::queue_position queue_position);
61 
62  ~mouse_motion();
63 
64  /**
65  * Captures the mouse input.
66  *
67  * When capturing the widget that has the mouse focus_ does the capturing.
68  *
69  * @param capture Set or release the capturing.
70  */
71  void capture_mouse(const bool capture = true);
72 
73 protected:
74  /** The widget that currently has the mouse focus_. */
76 
77  /** Did the current widget capture the focus_? */
79 
80  /** The widget that owns us. */
82 
83  /** The timer for the hover event. */
84  std::size_t hover_timer_;
85 
86  /** The widget which should get the hover event. */
88 
89  /** The anchor point of the hover event. */
91 
92  /**
93  * Has the hover been shown for the widget?
94  *
95  * A widget won't get a second hover event after the tooltip has been
96  * triggered. Only after (shortly) entering another widget it will be shown
97  * again for this widget.
98  */
100 
101  /**
102  * Starts the hover timer.
103  *
104  * @param widget The widget that wants the tooltip.
105  * @param coordinate The anchor coordinate.
106  */
108 
109  /** Stops the current hover timer. */
110  void stop_hover_timer();
111 
112  /**
113  * Called when the mouse enters a widget.
114  *
115  * @param mouse_over The widget that should receive the event.
116  */
117  void mouse_enter(widget* mouse_over);
118 
119  /** Called when the mouse leaves the current widget. */
120  void mouse_leave();
121 
122 private:
123  /**
124  * Called when the mouse moves over a widget.
125  *
126  * @param mouse_over The widget that should receive the event.
127  * @param coordinate The current screen coordinate of the mouse.
128  */
129  void mouse_hover(widget* mouse_over, const point& coordinate);
130 
131  /** Called when the mouse wants the widget to show its tooltip. */
132  void show_tooltip();
133 
135  void signal_handler_sdl_mouse_motion(const event::ui_event event, bool& handled, const point& coordinate);
136 
138  const event::ui_event event, bool& handled, const point& coordinate, const point& distance);
139 
140  void signal_handler_sdl_wheel(const event::ui_event event, bool& handled, const point& coordinate);
141 
142  void signal_handler_show_helptip(const event::ui_event event, bool& handled, const point& coordinate);
143 };
144 
145 /***** ***** ***** ***** mouse_button ***** ***** ***** ***** *****/
146 
147 template<std::size_t I>
148 class mouse_button : public virtual mouse_motion
149 {
150 public:
151  mouse_button(widget& owner, const dispatcher::queue_position queue_position);
152 
153  /**
154  * Initializes the state of the button.
155  *
156  * @param button_state The initial state of all buttons, in which the bit corresponding to
157  mouse_button_event_types.mask will be set if the button is down, or unset if it is up.
158  */
159  void initialize_state(int32_t button_state);
160 
161 protected:
162  /** The time of the last click used for double clicking. */
164 
165  /** The widget the last click was on, used for double clicking. */
167 
168  /**
169  * If the mouse isn't captured we need to verify the up is on the same
170  * widget as the down so we send a proper click, also needed to send the
171  * up to the right widget.
172  */
174 
175 private:
176  /** Is the button down? */
177  bool is_down_;
178 
180  void signal_handler_sdl_button_down(const event::ui_event event, bool& handled, const point& coordinate);
181 
183  void signal_handler_sdl_button_up(const event::ui_event event, bool& handled, const point& coordinate);
184 
186 };
187 
188 /***** ***** ***** ***** distributor ***** ***** ***** ***** *****/
189 
193 
194 /**
195  * The event handler class for the widget library.
196  *
197  * C++ doesn't allow multiple inheritance to directly use more than one instance of a
198  * superclass.
199  *
200  * It's a diamond inheritance, as all of these have virtual base class mouse_motion;
201  * refactoring that would allow these multiple classes to be replaced with a simple
202  * (distributor has-a std::array<mouse_button, 3>) relationship.
203  */
204 class distributor :
205  public mouse_button_left,
206  public mouse_button_middle,
207  public mouse_button_right
208 {
209 public:
210  distributor(widget& owner, const dispatcher::queue_position queue_position);
211 
212  ~distributor();
213 
214  /**
215  * Initializes the state of the keyboard and mouse.
216  *
217  * Needed after initialization and reactivation.
218  */
219  void initialize_state();
220 
221  /**
222  * Captures the keyboard input.
223  *
224  * @param widget The widget which should capture the keyboard.
225  * Sending nullptr releases the capturing.
226  */
228 
229  /**
230  * Adds the widget to the keyboard chain.
231  *
232  * @param widget The widget to add to the chain. The widget
233  * should be valid widget, which hasn't been
234  * added to the chain yet.
235  */
237 
238  /**
239  * Remove the widget from the keyboard chain.
240  *
241  * @param widget The widget to be removed from the chain.
242  */
244 
245  /**
246  * Return the widget currently capturing keyboard input.
247  */
248  widget* keyboard_focus() const;
249 
250 private:
251  /** The widget that holds the keyboard focus_. */
253 
254  /**
255  * Fall back keyboard focus_ items.
256  *
257  * When the focused widget didn't handle the keyboard event (or no handler
258  * for the keyboard focus_) it is send all widgets in this vector. The order
259  * is from rbegin() to rend(). If the keyboard_focus_ is in the vector it
260  * won't get the event twice. The first item added to the vector should be
261  * the window, so it will be the last handler and can dispatch the hotkeys
262  * registered.
263  */
264  std::vector<widget*> keyboard_focus_chain_;
265 
266  /**
267  * Set of functions that handle certain events and sends them to the proper
268  * widget. These functions are called by the SDL event handling functions.
269  */
270 
271  void signal_handler_sdl_key_down(const SDL_Keycode key,
272  const SDL_Keymod modifier,
273  const std::string& unicode);
274 
275  void signal_handler_sdl_text_input(const std::string& unicode, int32_t start, int32_t len);
276  void signal_handler_sdl_text_editing(const std::string& unicode, int32_t start, int32_t len);
277 
278  template<typename Fcn, typename P1, typename P2, typename P3>
279  void signal_handler_keyboard_internal(event::ui_event evt, P1&& p1, P2&& p2, P3&& p3);
280 
282 };
283 
284 } // namespace event
285 
286 } // namespace gui2
Base class for event handling.
Definition: dispatcher.hpp:150
queue_position
The position where to add a new callback in the signal handler.
Definition: dispatcher.hpp:331
The event handler class for the widget library.
widget * keyboard_focus_
The widget that holds the keyboard focus_.
void keyboard_add_to_chain(widget *widget)
Adds the widget to the keyboard chain.
void keyboard_capture(widget *widget)
Captures the keyboard input.
std::vector< widget * > keyboard_focus_chain_
Fall back keyboard focus_ items.
void signal_handler_keyboard_internal(event::ui_event evt, P1 &&p1, P2 &&p2, P3 &&p3)
void keyboard_remove_from_chain(widget *widget)
Remove the widget from the keyboard chain.
void signal_handler_sdl_text_editing(const std::string &unicode, int32_t start, int32_t len)
void signal_handler_sdl_key_down(const SDL_Keycode key, const SDL_Keymod modifier, const std::string &unicode)
Set of functions that handle certain events and sends them to the proper widget.
void initialize_state()
Initializes the state of the keyboard and mouse.
distributor(widget &owner, const dispatcher::queue_position queue_position)
widget * keyboard_focus() const
Return the widget currently capturing keyboard input.
void signal_handler_notify_removal(dispatcher &widget, const ui_event event)
void signal_handler_sdl_text_input(const std::string &unicode, int32_t start, int32_t len)
void signal_handler_sdl_button_down(const event::ui_event event, bool &handled, const point &coordinate)
widget * last_clicked_widget_
The widget the last click was on, used for double clicking.
mouse_button(widget &owner, const dispatcher::queue_position queue_position)
void initialize_state(int32_t button_state)
Initializes the state of the button.
bool is_down_
Is the button down?
void mouse_button_click(widget *widget)
uint32_t last_click_stamp_
The time of the last click used for double clicking.
void signal_handler_sdl_button_up(const event::ui_event event, bool &handled, const point &coordinate)
widget * focus_
If the mouse isn't captured we need to verify the up is on the same widget as the down so we send a p...
bool mouse_captured_
Did the current widget capture the focus_?
Definition: distributor.hpp:78
void mouse_hover(widget *mouse_over, const point &coordinate)
Called when the mouse moves over a widget.
widget * hover_widget_
The widget which should get the hover event.
Definition: distributor.hpp:87
void signal_handler_sdl_mouse_motion(const event::ui_event event, bool &handled, const point &coordinate)
mouse_motion(widget &owner, const dispatcher::queue_position queue_position)
Definition: distributor.cpp:67
void mouse_enter(widget *mouse_over)
Called when the mouse enters a widget.
bool hover_shown_
Has the hover been shown for the widget?
Definition: distributor.hpp:99
void signal_handler_sdl_touch_motion(const event::ui_event event, bool &handled, const point &coordinate, const point &distance)
void capture_mouse(const bool capture=true)
Captures the mouse input.
void signal_handler_show_helptip(const event::ui_event event, bool &handled, const point &coordinate)
void mouse_leave()
Called when the mouse leaves the current widget.
void signal_handler_sdl_wheel(const event::ui_event event, bool &handled, const point &coordinate)
point hover_position_
The anchor point of the hover event.
Definition: distributor.hpp:90
void stop_hover_timer()
Stops the current hover timer.
void start_hover_timer(widget *widget, const point &coordinate)
Starts the hover timer.
std::size_t hover_timer_
The timer for the hover event.
Definition: distributor.hpp:84
widget * mouse_focus_
The widget that currently has the mouse focus_.
Definition: distributor.hpp:75
widget & owner_
The widget that owns us.
Definition: distributor.hpp:81
void show_tooltip()
Called when the mouse wants the widget to show its tooltip.
Base class for all widgets.
Definition: widget.hpp:53
EXIT_STATUS start(bool clear_id, const std::string &filename, bool take_screenshot, const std::string &screenshot_filename)
Main interface for launching the editor from the title screen.
ui_event
The event sent to the dispatcher.
Definition: handler.hpp:115
Generic file dialog.
map_location coordinate
Contains an x and y coordinate used for starting positions in maps.
Holds a 2D point.
Definition: point.hpp:25