The Battle for Wesnoth  1.17.0-dev
menu_item.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2021
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 /**
17  * @file
18  * Declarations for a class that implements WML-defined (right-click) menu items.
19  */
20 
21 #pragma once
22 
23 #include "config.hpp"
24 #include "variable.hpp"
25 
26 class filter_context;
27 class game_data;
28 struct map_location;
29 
30 namespace game_events
31 {
33 {
34 public:
35  /**
36  * Constructor for reading from a saved config.
37  * This is the reverse of to_config() and corresponds to reading [menu_item].
38  * Handlers are not initialized.
39  */
40  wml_menu_item(const std::string& id, const config& cfg);
41 
42  /**
43  * Constructor for items defined in an event.
44  * This is where default values are defined (the other constructors should have
45  * all values to work with).
46  * @param[in] id The id of the menu item.
47  * @param[in] definition The WML defining this menu item.
48  */
49  wml_menu_item(const std::string& id, const vconfig& definition);
50 
51  /**
52  * Constructor for items modified by an event.
53  * (To avoid problems with a menu item's command changing itself, we make a
54  * new menu item instead of modifying the existing one.)
55  * @param[in] id The id of the menu item.
56  * @param[in] definition The WML defining this menu item.
57  * @param[in] original The previous version of the menu item with this id.
58  */
59  wml_menu_item(const std::string& id, const vconfig& definition, const wml_menu_item& original);
60 
61  /** The id of this item. */
62  const std::string& id() const
63  {
64  return item_id_;
65  }
66 
67  /**
68  * The image associated with this menu item.
69  * The returned string will not be empty; a default will be supplied if needed.
70  */
71  const std::string& image() const;
72 
73  /** If true, allow using the menu to trigger this item. */
74  bool use_wml_menu() const
75  {
76  return use_wml_menu_;
77  }
78 
79  /** If true, holding the hotkey will trigger this item repeatedly. */
80  bool hotkey_repeat() const
81  {
82  return default_hotkey_["repeat_on_hold"].to_bool(false);
83  }
84 
85  /**
86  * Returns whether or not *this is applicable given the context.
87  * Assumes game variables x1, y1, and unit have been set.
88  * @param[in] hex The hex where the menu will appear.
89  * @param[in] data Used to check whether to show if selecting is required.
90  * @param[in] context Used to check whether the menu's filter matches.
91  */
92  bool can_show(const map_location& hex, const game_data& data, filter_context& context) const;
93 
94  /**
95  * Causes the event associated with this item to fire.
96  * Also records the event.
97  * This includes recording the previous select event, if applicable.
98  * The undo stack will be cleared if the event mutated the gamestate.
99  *
100  * @param[in] event_hex The location of the event (where the menu was opened).
101  * @param[in] data The game data for the most recent "select" event.
102  */
103  void fire_event(const map_location& event_hex, const game_data& data) const;
104 
105  /** Removes the implicit event handler for an inlined [command]. */
106  void finish_handler() const;
107 
108  /** Initializes the implicit event handler for an inlined [command]. */
109  void init_handler() const;
110 
111  /**
112  * The text to put in a menu for this item.
113  * This will be either translated text or a hotkey identifier.
114  */
115  std::string menu_text() const
116  {
117  // The space is to prevent accidental hotkey binding.
118  return use_hotkey_ ? hotkey_id_ : description_.str() + ' ';
119  }
120 
121  /**
122  * Writes *this to the provided config.
123  * This is the reverse of the constructor from a config and corresponds to
124  * what will appear in [menu_item].
125  */
126  void to_config(config& cfg) const;
127 
128  bool is_synced() const
129  {
130  return is_synced_;
131  }
132 
133 private:
134  /**
135  * Updates *this based on @a vcfg.
136  * This corresponds to what can appear in [set_menu_item].
137  */
138  void update(const vconfig& vcfg);
139 
140  /** Updates our command to @a new_command. */
141  void update_command(const config& new_command);
142 
143 private:
144  /** The id of this menu item. */
145  const std::string item_id_;
146 
147  /** The name of this item's event(s); based on the item's id. */
148  const std::string event_name_;
149 
150  /** The id for this item's hotkey; based on the item's id. */
151  const std::string hotkey_id_;
152 
153  /** The image to display in the menu next to this item's description. */
154  std::string image_;
155 
156  /** The text to display in the menu for this item. */
158 
159  /** Whether or not this event says it makes use of the last selected unit. */
161 
162  /**
163  * A condition that must hold in order for this menu item to be visible.
164  * (An empty condition always holds.)
165  *
166  * When used, we need a vconfig instead of a config.
167  */
169 
170  /**
171  * A location filter to be applied to the hex where the menu is invoked.
172  * (An empty filter always passes.)
173  *
174  * When used, we need a vconfig instead of a config.
175  */
177 
178  /** Actions to take when this item is chosen. */
180 
181  /** Config object containing the default hotkey. */
183 
184  /** If true, allow using a hotkey to trigger this item. */
186 
187  /** If true, allow using the menu to trigger this item. */
189 
190  /**
191  * If true, this item will be sent to the clients.
192  * The command shall not change the gamestate if !is_synced_
193  */
195 
196  /** If true, keep this menu item in later scenarios. */
198 };
199 
200 } // end namespace game_events
void to_config(config &cfg) const
Writes *this to the provided config.
Definition: menu_item.cpp:219
bool needs_select_
Whether or not this event says it makes use of the last selected unit.
Definition: menu_item.hpp:160
bool use_wml_menu() const
If true, allow using the menu to trigger this item.
Definition: menu_item.hpp:74
bool hotkey_repeat() const
If true, holding the hotkey will trigger this item repeatedly.
Definition: menu_item.hpp:80
vconfig filter_location_
A location filter to be applied to the hex where the menu is invoked.
Definition: menu_item.hpp:176
config command_
Actions to take when this item is chosen.
Definition: menu_item.hpp:179
void fire_event(const map_location &event_hex, const game_data &data) const
Causes the event associated with this item to fire.
Definition: menu_item.cpp:164
t_string description_
The text to display in the menu for this item.
Definition: menu_item.hpp:157
const std::string & image() const
The image associated with this menu item.
Definition: menu_item.cpp:136
std::string image_
The image to display in the menu next to this item&#39;s description.
Definition: menu_item.hpp:154
bool can_show(const map_location &hex, const game_data &data, filter_context &context) const
Returns whether or not *this is applicable given the context.
Definition: menu_item.cpp:143
Definitions for the interface to Wesnoth Markup Language (WML).
void finish_handler() const
Removes the implicit event handler for an inlined [command].
Definition: menu_item.cpp:192
vconfig show_if_
A condition that must hold in order for this menu item to be visible.
Definition: menu_item.hpp:168
const std::string item_id_
The id of this menu item.
Definition: menu_item.hpp:145
Encapsulates the map of the game.
Definition: location.hpp:38
void init_handler() const
Initializes the implicit event handler for an inlined [command].
Definition: menu_item.cpp:205
Domain specific events.
Definition: action_wml.cpp:87
bool is_synced_
If true, this item will be sent to the clients.
Definition: menu_item.hpp:194
bool persistent_
If true, keep this menu item in later scenarios.
Definition: menu_item.hpp:197
bool use_hotkey_
If true, allow using a hotkey to trigger this item.
Definition: menu_item.hpp:185
A variable-expanding proxy for the config class.
Definition: variable.hpp:44
std::string menu_text() const
The text to put in a menu for this item.
Definition: menu_item.hpp:115
bool use_wml_menu_
If true, allow using the menu to trigger this item.
Definition: menu_item.hpp:188
const std::string & id() const
The id of this item.
Definition: menu_item.hpp:62
wml_menu_item(const std::string &id, const config &cfg)
Constructor for reading from a saved config.
Definition: menu_item.cpp:69
void update_command(const config &new_command)
Updates our command to new_command.
Definition: menu_item.cpp:336
void update(const vconfig &vcfg)
Updates *this based on vcfg.
Definition: menu_item.cpp:265
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:61
const std::string & str() const
Definition: tstring.hpp:191
const std::string event_name_
The name of this item&#39;s event(s); based on the item&#39;s id.
Definition: menu_item.hpp:148
const std::string hotkey_id_
The id for this item&#39;s hotkey; based on the item&#39;s id.
Definition: menu_item.hpp:151
config default_hotkey_
Config object containing the default hotkey.
Definition: menu_item.hpp:182