The Battle for Wesnoth  1.19.13+dev
hotkey_item.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 <memory>
20 #include <vector>
21 #include <string>
22 
23 class game_config_view;
24 class config;
25 namespace hotkey {
26 
27 typedef std::shared_ptr<class hotkey_base> hotkey_ptr;
28 typedef std::shared_ptr<class hotkey_mouse> hotkey_mouse_ptr;
29 typedef std::shared_ptr<class hotkey_keyboard> hotkey_keyboard_ptr;
30 
31 typedef std::vector<hotkey::hotkey_ptr> hotkey_list;
32 
33 /**
34  * This is the base class for hotkey event matching.
35  */
37 {
38 public:
39  /**
40  * Initialises a new empty hotkey that will be disabled
41  */
42  hotkey_base() : command_("null"), is_default_(true), is_disabled_(false), mod_(0)
43  {}
44 
45  void set_command(const std::string& command)
46  {
47  command_ = command;
48  }
49 
50  /**
51  * Set keyboard modifiers.
52  * @param mods Bitmask of SDL_Keymod.
53  */
54  void set_mods(unsigned int mods)
55  {
56  mod_ = mods;
57  }
58 
59  /**
60  * Returns the string name of the HOTKEY_COMMAND
61  * @return The unique string for a hotkey command.
62  **/
63  const std::string& get_command() const
64  {
65  return command_;
66  }
67 
68  /**
69  * This controls whether the item should appear in the hotkey preferences.
70  * @return true if the item should be hidden
71  **/
72  virtual bool hidden() const
73  {
74  return false;
75  }
76 
77  /**
78  * This indicates whether a hotkey is from the default config or if it's
79  * from the user preferences.
80  * @return true if from the default configurations, false otherwise
81  */
82  bool is_default() const
83  {
84  return is_default_;
85  }
86 
87  /**
88  * Used to indicate that a hotkey is overridden and should be treated as
89  * a user-set hotkey.
90  */
92  {
93  is_default_ = false;
94  }
95 
96  bool is_disabled() const
97  {
98  return is_disabled_;
99  }
100  void disable()
101  {
102  is_disabled_ = true;
103  }
104  void enable()
105  {
106  is_disabled_ = false;
107  }
108 
109  /**
110  * Unbind this hotkey by linking it to the null-command
111  */
112  void clear()
113  {
114  command_ = "null";
115  }
116 
117  /**
118  * Returns whether this hotkey points to the null-command
119  * @return true if it points to the null-command, false otherwise.
120  */
121  bool null() const
122  {
123  return command_ == "null";
124  }
125 
126  /*
127  * Returns whether there is a associated hotkey_command.
128  * If the none of the hotkey_commands fits this hotkey_item then
129  * @param get_hotkey_command will return the hotkey_command::null_command().
130  * @return true if the hotkey is not bound to the null-command.
131  */
132  bool active() const
133  {
134  return command_ != "null";
135  }
136 
137  /**
138  * Evaluates whether the hotkey bindings are valid.
139  * @return true if they are valid, false otherwise.
140  */
141  virtual bool valid() const = 0;
142 
143  /**
144  * Save the hotkey into the configuration object.
145  * @param cfg The configuration object to save into.
146  */
147  void save(config& cfg) const;
148 
149  /**
150  * Return "name" of hotkey. Example :"ctrl+alt+g"
151  * @return The string representation of the keybindings
152  */
153  std::string get_name() const;
154 
155  /**
156  * Used to evaluate whether:
157  * 1. The hotkey is valid in the current scope.
158  * 2. The Keyboard modifiers and SDL_Event matches this hotkey.
159  *
160  * @param event The SDL_Event that has triggered and is being evaluated.
161  */
162  bool matches(const SDL_Event& event) const;
163 
164  /**
165  * Checks whether the hotkey bindings and scope are equal.
166  * @param other the hokey bindings to compare against.
167  * @return true if %other has same scope and bindings.
168  */
169  virtual bool bindings_equal(const hotkey_ptr& other);
170 
171  virtual ~hotkey_base()
172  {}
173 
174 protected:
175  /**
176  * This is invoked by hotkey_base::get_name and must be implemented by subclasses.
177  * Keyboard modifiers are handled in this class, other hotkeys in the respective classes
178  */
179  virtual const std::string get_name_helper() const = 0;
180  /**
181  * This is invoked by hotkey_base::matches as a helper for the concrete classes.
182  * Implementing classes should only check their parts of the hotkey.
183  * @param event The SDL_Event being generated.
184  * @returns true if they match, false otherwise.
185  */
186  virtual bool matches_helper(const SDL_Event &event) const = 0;
187  virtual void save_helper(config& cfg) const = 0;
188  /**
189  * This is invoked by hotkey_base::bindings_equal as a helper for the concrete classes.
190  * Implementing classes should only check their parts of the hotkey.
191  * @param other The other hotkey the check against. Not guaranteed to be the same subclass.
192  * @returns true if they match, false otherwise.
193  */
194  virtual bool bindings_equal_helper(hotkey_ptr other) const = 0;
195 
196  /**
197  * The command that should be executed, or "null".
198  */
199  std::string command_;
200 
201  /**
202  * is_default_ is true if the hot-key is part of the default hot-key list defined in data/core/hotkeys.cfg.
203  * is_default_ is false if it is not, in which case it would be defined in the user's preferences file.
204  */
206 
207  /*
208  * The original design of using a "null" command to indicate a disabled hot-key is ambiguous with regards
209  * to when to save a user hot-key to preferences as well as when a default hot-key should be flagged as
210  * disabled. So introduce a separate disabled flag to resolve the ambiguity.
211  * Where the flag is true, the hot-key should not be written to preferences unless it is a default hot-key.
212  */
214 
215  /*
216  * Keyboard modifiers. Treat as opaque, only do comparisons.
217  */
218  unsigned int mod_;
219 };
220 
221 /**
222  * This class is responsible for handling keys, not modifiers.
223  */
225 {
226 public:
227  /**
228  * Initialise new instance of this class that has no key associated with is.
229  */
230  hotkey_keyboard() : hotkey_base(), keycode_(SDLK_UNKNOWN), text_("")
231  {}
232 
233  /**
234  * Set the keycode associated with this class.
235  * @param keycode The SDL_Keycode that this hotkey should be associated with
236  */
237  void set_keycode(SDL_Keycode keycode)
238  {
239  keycode_ = keycode;
240  }
241 
242  void set_text(const std::string& text);
243 
244  /**
245  * Checks whether this hotkey has been set to a sensible value.
246  * @ return true if it is a known key
247  */
248  virtual bool valid() const
249  {
250  return keycode_ != SDLK_UNKNOWN && !text_.empty();
251  }
252 
253 protected:
254  SDL_Keycode keycode_;
255  std::string text_;
256 
257  virtual void save_helper(config& cfg) const;
258  virtual const std::string get_name_helper() const;
259  virtual bool matches_helper(const SDL_Event &event) const;
260  virtual bool bindings_equal_helper (hotkey_ptr other) const;
261 };
262 
263 /**
264  * This class is used to return non-valid results in order to save
265  * other people from null checks.
266  */
268 {
269 public:
271  {}
272  virtual bool valid() const
273  {
274  return false;
275  }
276 protected:
277  virtual void save_helper(config&) const
278  {}
279  virtual const std::string get_name_helper() const
280  {
281  return "";
282  }
283  virtual bool matches_helper(const SDL_Event&) const
284  {
285  return false;
286  }
287  virtual bool bindings_equal_helper(hotkey_ptr) const
288  {
289  return false;
290  }
291 };
292 
293 /**
294  * This class is responsible for handling mouse button presses.
295  */
297 {
298 public:
299  /**
300  * Initialise new instance of this class that has no button associated with is.
301  */
303  {}
304 
305  /**
306  * Returns true if the hotkey has a valid mouse button associated with it.
307  * @return true if a mouse button is set, false otherwise.
308  */
309  virtual bool valid() const
310  {
311  return button_ != 0;
312  }
313 
314  /* new functionality for this class */
315  void set_button(int button)
316  {
317  button_ = button;
318  }
319 protected:
320  int button_;
321 
322  virtual void save_helper(config& cfg) const;
323  virtual const std::string get_name_helper() const;
324  virtual bool matches_helper(const SDL_Event &event) const;
325  virtual bool bindings_equal_helper (hotkey_ptr other) const;
326 };
327 
328 /**
329  * Create and instantiate a hotkey from a config element.
330  * @param cfg The config element to read for data.
331  * @return The new instance of the hotkey item.
332  */
334 
335 /*
336  * Scans the list of hotkeys to see if one has been bound to the command.
337  * @param command The command that is searched for
338  * @return true if there is a hotkey item that has the command bound.
339  */
340 bool has_hotkey_item(const std::string& command);
341 
342 /**
343  * Add a hotkey to the list of hotkeys.
344  * @param item The item to add.
345  */
346 void add_hotkey(hotkey_ptr item);
347 
348 /**
349  * Create a new hotkey item for a command from an SDL_Event.
350  * @param id The command to bind to.
351  * @param event The SDL_Event to base the creation on.
352  */
353 hotkey_ptr create_hotkey(const std::string &id, const SDL_Event &event);
354 
355 /**
356  * Iterate through the list of hotkeys and return a hotkey that matches
357  * the SDL_Event and the current keyboard modifier state.
358  * @param event The SDL_Event to use as a template.
359  * @return The newly created hotkey item.
360  */
361 const hotkey_ptr get_hotkey(const SDL_Event &event);
362 
363 /**
364  * Registers all hotkeys present in this config.
365  *
366  * @param cfg The config to load from. This is saved and is used again when
367  * @ref reset_default_hotkeys is called.
368  */
369 void load_default_hotkeys(const game_config_view& cfg);
370 
371 /**
372  * Registers all hotkeys present in this config, overwriting any matching default hotkeys.
373  *
374  * @param cfg The config to load from.
375  */
376 void load_custom_hotkeys(const game_config_view& cfg);
377 
378 /**
379  * Reset all hotkeys to the defaults.
380  */
381 void reset_default_hotkeys();
382 
383 /**
384  * Returns the list of hotkeys.
385  */
386 const hotkey_list& get_hotkeys();
387 
388 /**
389  * Unset the command bindings for all hotkeys matching the command.
390  *
391  * @param command The binding to be unset
392  */
393 void clear_hotkeys(const std::string& command);
394 
395 /**
396  * Unset the bindings for all hotkeys.
397  */
398 void clear_hotkeys();
399 
400 /**
401  * Returns a comma-separated string of hotkey names. A hotkey name is in the form of
402  * "ctrl+l" or "n" or "mouse 1". The comman separated string is of the form "ctrl+l,n,mouse 1".
403  * @return The comma separated string of hotkey names.
404  */
405 std::string get_names(const std::string& id);
406 
407 /**
408  * Save the non-default hotkeys to the config.
409  * @param cfg The config to save to.
410  */
411 void save_hotkeys(config& cfg);
412 
413 bool is_hotkeyable_event(const SDL_Event &event);
414 
415 }
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:158
A class grating read only view to a vector of config objects, viewed as one config with all children ...
This is the base class for hotkey event matching.
Definition: hotkey_item.hpp:37
void set_command(const std::string &command)
Definition: hotkey_item.hpp:45
void clear()
Unbind this hotkey by linking it to the null-command.
bool is_disabled() const
Definition: hotkey_item.hpp:96
virtual void save_helper(config &cfg) const =0
const std::string & get_command() const
Returns the string name of the HOTKEY_COMMAND.
Definition: hotkey_item.hpp:63
void unset_default()
Used to indicate that a hotkey is overridden and should be treated as a user-set hotkey.
Definition: hotkey_item.hpp:91
std::string get_name() const
Return "name" of hotkey.
Definition: hotkey_item.cpp:49
virtual bool bindings_equal(const hotkey_ptr &other)
Checks whether the hotkey bindings and scope are equal.
Definition: hotkey_item.cpp:84
hotkey_base()
Initialises a new empty hotkey that will be disabled.
Definition: hotkey_item.hpp:42
bool is_default() const
This indicates whether a hotkey is from the default config or if it's from the user preferences.
Definition: hotkey_item.hpp:82
virtual bool hidden() const
This controls whether the item should appear in the hotkey preferences.
Definition: hotkey_item.hpp:72
void save(config &cfg) const
Save the hotkey into the configuration object.
bool active() const
bool is_default_
is_default_ is true if the hot-key is part of the default hot-key list defined in data/core/hotkeys....
void set_mods(unsigned int mods)
Set keyboard modifiers.
Definition: hotkey_item.hpp:54
virtual bool valid() const =0
Evaluates whether the hotkey bindings are valid.
virtual bool bindings_equal_helper(hotkey_ptr other) const =0
This is invoked by hotkey_base::bindings_equal as a helper for the concrete classes.
bool matches(const SDL_Event &event) const
Used to evaluate whether:
std::string command_
The command that should be executed, or "null".
virtual const std::string get_name_helper() const =0
This is invoked by hotkey_base::get_name and must be implemented by subclasses.
virtual bool matches_helper(const SDL_Event &event) const =0
This is invoked by hotkey_base::matches as a helper for the concrete classes.
This class is responsible for handling keys, not modifiers.
void set_text(const std::string &text)
virtual bool valid() const
Checks whether this hotkey has been set to a sensible value.
virtual void save_helper(config &cfg) const
virtual const std::string get_name_helper() const
This is invoked by hotkey_base::get_name and must be implemented by subclasses.
hotkey_keyboard()
Initialise new instance of this class that has no key associated with is.
virtual bool bindings_equal_helper(hotkey_ptr other) const
This is invoked by hotkey_base::bindings_equal as a helper for the concrete classes.
void set_keycode(SDL_Keycode keycode)
Set the keycode associated with this class.
virtual bool matches_helper(const SDL_Event &event) const
This is invoked by hotkey_base::matches as a helper for the concrete classes.
This class is responsible for handling mouse button presses.
virtual const std::string get_name_helper() const
This is invoked by hotkey_base::get_name and must be implemented by subclasses.
virtual void save_helper(config &cfg) const
void set_button(int button)
virtual bool valid() const
Returns true if the hotkey has a valid mouse button associated with it.
virtual bool matches_helper(const SDL_Event &event) const
This is invoked by hotkey_base::matches as a helper for the concrete classes.
virtual bool bindings_equal_helper(hotkey_ptr other) const
This is invoked by hotkey_base::bindings_equal as a helper for the concrete classes.
hotkey_mouse()
Initialise new instance of this class that has no button associated with is.
This class is used to return non-valid results in order to save other people from null checks.
virtual const std::string get_name_helper() const
This is invoked by hotkey_base::get_name and must be implemented by subclasses.
virtual void save_helper(config &) const
virtual bool valid() const
Evaluates whether the hotkey bindings are valid.
virtual bool bindings_equal_helper(hotkey_ptr) const
This is invoked by hotkey_base::bindings_equal as a helper for the concrete classes.
virtual bool matches_helper(const SDL_Event &) const
This is invoked by hotkey_base::matches as a helper for the concrete classes.
Keyboard shortcuts for game actions.
const hotkey_list & get_hotkeys()
Returns the list of hotkeys.
std::string get_names(const std::string &id)
Returns a comma-separated string of hotkey names.
void save_hotkeys(config &cfg)
Save the non-default hotkeys to the config.
std::shared_ptr< class hotkey_keyboard > hotkey_keyboard_ptr
Definition: hotkey_item.hpp:29
std::shared_ptr< class hotkey_base > hotkey_ptr
Definition: hotkey_item.hpp:27
bool has_hotkey_item(const std::string &command)
const hotkey_ptr get_hotkey(const SDL_Event &event)
Iterate through the list of hotkeys and return a hotkey that matches the SDL_Event and the current ke...
void clear_hotkeys(const std::string &command)
Unset the command bindings for all hotkeys matching the command.
void reset_default_hotkeys()
Reset all hotkeys to the defaults.
hotkey_ptr load_from_config(const config &cfg)
Create and instantiate a hotkey from a config element.
hotkey_ptr create_hotkey(const std::string &id, const SDL_Event &event)
Create a new hotkey item for a command from an SDL_Event.
std::shared_ptr< class hotkey_mouse > hotkey_mouse_ptr
Definition: hotkey_item.hpp:28
std::vector< hotkey::hotkey_ptr > hotkey_list
Definition: hotkey_item.hpp:31
void load_custom_hotkeys(const game_config_view &cfg)
Registers all hotkeys present in this config, overwriting any matching default hotkeys.
void load_default_hotkeys(const game_config_view &cfg)
Registers all hotkeys present in this config.
void add_hotkey(hotkey_ptr item)
Add a hotkey to the list of hotkeys.
bool is_hotkeyable_event(const SDL_Event &event)