The Battle for Wesnoth  1.19.14+dev
events.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2025
3  by David White <dave@whitevine.net>
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 <SDL2/SDL_events.h>
19 #include <vector>
20 #include <list>
21 #include <functional>
22 
23 //our user-defined double-click event type
24 #define TIMER_EVENT (SDL_USEREVENT + 1)
25 #define HOVER_REMOVE_POPUP_EVENT (SDL_USEREVENT + 2)
26 #define DRAW_EVENT (SDL_USEREVENT + 3)
27 #define CLOSE_WINDOW_EVENT (SDL_USEREVENT + 4)
28 #define SHOW_HELPTIP_EVENT (SDL_USEREVENT + 5)
29 #define INVOKE_FUNCTION_EVENT (SDL_USEREVENT + 6)
30 
31 namespace events
32 {
33 
34 class sdl_handler;
35 
36 typedef std::list<sdl_handler*> handler_list;
37 
38 class context
39 {
40 public:
41  context() :
42  handlers(),
45  {
46  }
47 
48  ~context();
49 
50  context(const context&) = delete;
51 
52  void add_handler(sdl_handler* ptr);
53  /** Returns true if @a ptr is found in either the handlers or staging_handlers lists */
54  bool has_handler(const sdl_handler* ptr) const;
55  bool remove_handler(sdl_handler* ptr);
56  void cycle_focus();
57  void set_focus(const sdl_handler* ptr);
58  void add_staging_handlers();
59 
62  std::vector<sdl_handler*> staging_handlers;
63 };
64 
65 //any classes that derive from this class will automatically
66 //receive sdl events through the handle function for their lifetime,
67 //while the event context they were created in is active.
68 //
69 //NOTE: an event_context object must be initialized before a handler object
70 //can be initialized, and the event_context must be destroyed after
71 //the handler is destroyed.
73 {
74 friend class context;
75 public:
76  virtual void handle_event(const SDL_Event& event) = 0;
77  virtual void handle_window_event(const SDL_Event&) {};
78  virtual void process_event() {}
79 
80  virtual bool requires_event_focus(const SDL_Event * = nullptr) const { return false; }
81 
82  virtual void process_tooltip_string(int /*mousex*/, int /*mousey*/) {}
83 
84  virtual void join(); /*joins the current event context*/
85  virtual void join(context &c); /*joins the specified event context*/
86  virtual void join_same(sdl_handler* parent); /*joins the same event context as the parent is already associated with */
87  virtual void leave(); /*leave the event context*/
88 
89  virtual void join_global(); /*join the global event context*/
90  virtual void leave_global(); /*leave the global event context*/
91 
92  virtual bool has_joined() { return has_joined_;}
93  virtual bool has_joined_global() { return has_joined_global_;}
94 
95  /**
96  * Moving would require two instances' context membership to be handled,
97  * it's simpler to delete these and require the two instances to be
98  * separately constructed / destructed.
99  */
101  sdl_handler(sdl_handler &&) = delete;
102 
103 protected:
104  sdl_handler(const bool auto_join=true);
105  sdl_handler(const sdl_handler &);
107  virtual ~sdl_handler();
108  virtual std::vector<sdl_handler*> handler_members()
109  {
110  return std::vector<sdl_handler*>();
111  }
112 
113 private:
116 };
117 
118 void focus_handler(const sdl_handler* ptr);
119 
120 bool has_focus(const sdl_handler* ptr, const SDL_Event* event);
121 
122 void set_main_thread();
123 
124 // whether the currently executing thread is the main thread.
125 bool is_in_main_thread();
126 
127 void call_in_main_thread(const std::function<void (void)>& f);
128 
129 //event_context objects control the handler objects that SDL events are sent
130 //to. When an event_context is created, it will become the current event context.
131 //event_context objects MUST be created in LIFO ordering in relation to each other,
132 //and in relation to handler objects. That is, all event_context objects should be
133 //created as automatic/stack variables.
134 //
135 //handler objects need not be created as automatic variables (e.g. you could put
136 //them in a vector) however you must guarantee that handler objects are destroyed
137 //before their context is destroyed
139 {
140  event_context();
141  ~event_context();
142 };
143 
144 /** Process all events currently in the queue. */
145 void pump();
146 
147 /** Trigger a draw cycle. */
148 void draw();
149 
150 /** pump() then immediately draw() */
151 inline void pump_and_draw() { pump(); draw(); }
152 // TODO: draw_manager - should this also raise_process_event? Some things do some don't
153 
155 //pump_monitors receive notification after an events::pump() occurs
156 public:
157  pump_monitor();
158  virtual ~pump_monitor();
159  virtual void process() = 0;
160 };
161 
162 void raise_process_event();
163 void raise_resize_event();
164 /**
165  * Triggered by mouse-motion, sends the cursor position to all handlers to
166  * check whether a tooltip should be shown.
167  */
168 void process_tooltip_strings(int mousex, int mousey);
169 
170 
171 /**
172  * Is the event an input event?
173  *
174  * @returns Whether or not the event is an input event.
175  */
176 bool is_input(const SDL_Event& event);
177 
178 /**
179  * Check if this mouse button event is caused by a touch
180  *
181  * @returns Whether or not this event is caused by a touch
182  */
183 bool is_touch(const SDL_MouseButtonEvent& event);
184 
185 /**
186  * Check if this mouse motion event is caused by a touch
187  *
188  * @returns Whether or not this event is caused by a touch
189  */
190 bool is_touch(const SDL_MouseMotionEvent& event);
191 
192 /** Discards all input events. */
193 void discard_input();
194 
195 }
196 
197 typedef std::vector<events::sdl_handler*> sdl_handler_vector;
void set_focus(const sdl_handler *ptr)
Definition: events.cpp:186
bool has_handler(const sdl_handler *ptr) const
Returns true if ptr is found in either the handlers or staging_handlers lists.
Definition: events.cpp:98
void cycle_focus()
Definition: events.cpp:153
handler_list::iterator focused_handler
Definition: events.hpp:61
std::vector< sdl_handler * > staging_handlers
Definition: events.hpp:62
handler_list handlers
Definition: events.hpp:60
context(const context &)=delete
void add_handler(sdl_handler *ptr)
Definition: events.cpp:89
bool remove_handler(sdl_handler *ptr)
Definition: events.cpp:106
void add_staging_handlers()
Definition: events.cpp:194
virtual ~pump_monitor()
Definition: events.cpp:227
virtual void process()=0
virtual bool requires_event_focus(const SDL_Event *=nullptr) const
Definition: events.hpp:80
virtual void process_tooltip_string(int, int)
Definition: events.hpp:82
virtual void handle_window_event(const SDL_Event &)
Definition: events.hpp:77
virtual bool has_joined_global()
Definition: events.hpp:93
virtual bool has_joined()
Definition: events.hpp:92
virtual std::vector< sdl_handler * > handler_members()
Definition: events.hpp:108
virtual void join()
Definition: events.cpp:308
virtual void leave()
Definition: events.cpp:353
virtual void handle_event(const SDL_Event &event)=0
virtual void process_event()
Definition: events.hpp:78
virtual void join_global()
Definition: events.cpp:374
virtual void join_same(sdl_handler *parent)
Definition: events.cpp:337
virtual void leave_global()
Definition: events.cpp:394
sdl_handler & operator=(sdl_handler &&)=delete
Moving would require two instances' context membership to be handled, it's simpler to delete these an...
virtual ~sdl_handler()
Definition: events.cpp:297
sdl_handler(sdl_handler &&)=delete
std::vector< events::sdl_handler * > sdl_handler_vector
Definition: events.hpp:197
Handling of system events.
void raise_resize_event()
Definition: events.cpp:735
bool has_focus(const sdl_handler *hand, const SDL_Event *event)
Definition: events.cpp:412
void discard_input()
Discards all input events.
Definition: events.cpp:766
void draw()
Trigger a draw cycle.
Definition: events.cpp:719
bool is_input(const SDL_Event &event)
Is the event an input event?
Definition: events.cpp:761
void set_main_thread()
Definition: events.cpp:471
void call_in_main_thread(const std::function< void(void)> &f)
Definition: events.cpp:781
void raise_process_event()
Definition: events.cpp:724
void process_tooltip_strings(int mousex, int mousey)
Triggered by mouse-motion, sends the cursor position to all handlers to check whether a tooltip shoul...
Definition: events.cpp:748
std::list< sdl_handler * > handler_list
Definition: events.hpp:34
bool is_in_main_thread()
Definition: events.cpp:478
void pump_and_draw()
pump() then immediately draw()
Definition: events.hpp:151
void pump()
Process all events currently in the queue.
Definition: events.cpp:483
bool is_touch(const SDL_MouseButtonEvent &event)
Check if this mouse button event is caused by a touch.
Definition: events.cpp:771
void focus_handler(const sdl_handler *ptr)
Definition: events.cpp:405
std::string::const_iterator iterator
Definition: tokenizer.hpp:25
mock_char c
#define f