The Battle for Wesnoth  1.17.17+dev
handlers.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2023
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  * Define the handlers for the game's events mechanism.
19  *
20  * Events might be units moving or fighting, or when victory or defeat occurs.
21  * A scenario's configuration file will define actions to take when certain events occur.
22  * This module is responsible for tracking these definitions.
23  */
24 
25 #pragma once
26 
27 #include "config.hpp"
28 
29 #include <string>
30 
31 class game_data;
32 class game_lua_kernel;
33 class variable_set;
34 
35 namespace game_events
36 {
37 struct queued_event;
38 /** Represents a single filter condition on an event. */
39 struct event_filter {
40  /** Runs the filter and returns whether it passes on the given event. */
41  virtual bool operator()(const queued_event& event_info) const = 0;
42  /** Serializes the filter into a config, if possible. */
43  virtual void serialize(config& cfg) const;
44  /** Returns true if it is possible to serialize the filter into a config. */
45  virtual bool can_serialize() const;
46  virtual ~event_filter() = default;
47  event_filter() = default;
48 private:
49  event_filter(const event_filter&) = delete;
50  event_filter& operator=(const event_filter&) = delete;
51 };
52 
54 {
55 public:
56  event_handler(const std::string& types, const std::string& id = "");
57 
58  std::vector<std::string> names(const variable_set* vars) const;
59  const std::string& names_raw() const
60  {
61  return types_;
62  }
63 
64  bool disabled() const
65  {
66  return disabled_;
67  }
68 
69  bool is_menu_item() const
70  {
71  return is_menu_item_;
72  }
73 
74  /** Flag this handler as disabled. */
75  void disable();
76 
77  /**
78  * Handles the queued event, according to our WML instructions.
79  *
80  * @param[in] event_info Information about the event that needs handling.
81  * @param[in] lk The lua kernel to run the WML command.
82  */
83  void handle_event(const queued_event& event_info, game_lua_kernel& lk);
84 
85  bool filter_event(const queued_event& event_info) const;
86 
87  const config& arguments() const
88  {
89  return args_;
90  }
91 
92  const std::string& id() const
93  {
94  return id_;
95  }
96 
97  bool empty() const;
98 
99  bool repeatable() const
100  {
101  return !first_time_only_;
102  }
103 
104  // Normally non-serializable events are skipped when serializing (with a warning).
105  // If include_nonserializable is true, the game attempts to serialize them anyway.
106  // This will produce output that kind of looks like the event but would not deserialize to the same event.
107  void write_config(config& cfg, bool include_nonserializable = false) const;
108 
109  void set_repeatable(bool repeat = true)
110  {
111  first_time_only_ = !repeat;
112  }
113 
114  void set_menu_item(bool imi)
115  {
116  is_menu_item_ = imi;
117  }
118 
119  void set_arguments(const config& cfg)
120  {
121  args_ = cfg;
122  }
123 
124  void read_filters(const config& cfg);
125  void add_filter(std::unique_ptr<event_filter>&& filter);
126 
128  void set_event_ref(int idx, bool has_preloaded);
129 
130 private:
133  bool disabled_;
134  /**
135  * Tracks whether the event was registered from the Lua API.
136  * This allows a warning to be issued in cases that will break saved games.
137  */
138  bool is_lua_;
139  /**
140  * Tracks whether the event was registered before or after the Lua preload event fired.
141  * This allows a warning to be issued in cases that will break saved games.
142  *
143  * Rationale: Events where the filter or action is a Lua function cannot be serialized.
144  * Therefore, if a saved game relies on it being serialized, it will fail.
145  * Events registered during or before preload do not need to be serialized, because when
146  * a saved game is loaded, the preload event re-triggers and re-registers the event.
147  * This is actually a common use-case for the Lua events API.
148  * So, this flag allows avoiding false positives in the warning message.
149  */
153  std::vector<std::shared_ptr<event_filter>> filters_;
154  std::string id_, types_;
155 };
156 
157 }
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:161
void set_arguments(const config &cfg)
Definition: handlers.hpp:119
bool has_preloaded_
Tracks whether the event was registered before or after the Lua preload event fired.
Definition: handlers.hpp:150
void register_wml_event(game_lua_kernel &lk)
Definition: handlers.cpp:377
void add_filter(std::unique_ptr< event_filter > &&filter)
Definition: handlers.cpp:372
void read_filters(const config &cfg)
Definition: handlers.cpp:357
void write_config(config &cfg, bool include_nonserializable=false) const
Definition: handlers.cpp:126
const std::string & id() const
Definition: handlers.hpp:92
std::vector< std::string > names(const variable_set *vars) const
Definition: handlers.cpp:64
const config & arguments() const
Definition: handlers.hpp:87
void set_event_ref(int idx, bool has_preloaded)
Definition: handlers.cpp:382
void set_menu_item(bool imi)
Definition: handlers.hpp:114
bool is_menu_item() const
Definition: handlers.hpp:69
void disable()
Flag this handler as disabled.
Definition: handlers.cpp:95
event_handler(const std::string &types, const std::string &id="")
Definition: handlers.cpp:55
bool filter_event(const queued_event &event_info) const
Definition: handlers.cpp:119
bool is_lua_
Tracks whether the event was registered from the Lua API.
Definition: handlers.hpp:138
const std::string & names_raw() const
Definition: handlers.hpp:59
std::vector< std::shared_ptr< event_filter > > filters_
Definition: handlers.hpp:153
void set_repeatable(bool repeat=true)
Definition: handlers.hpp:109
void handle_event(const queued_event &event_info, game_lua_kernel &lk)
Handles the queued event, according to our WML instructions.
Definition: handlers.cpp:101
Domain specific events.
Represents a single filter condition on an event.
Definition: handlers.hpp:39
event_filter & operator=(const event_filter &)=delete
virtual void serialize(config &cfg) const
Serializes the filter into a config, if possible.
Definition: handlers.cpp:172
virtual ~event_filter()=default
virtual bool can_serialize() const
Returns true if it is possible to serialize the filter into a config.
Definition: handlers.cpp:177
virtual bool operator()(const queued_event &event_info) const =0
Runs the filter and returns whether it passes on the given event.
event_filter(const event_filter &)=delete