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