The Battle for Wesnoth  1.19.0-dev
handlers.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2024
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  const double& priority() const
98  {
99  return priority_;
100  }
101 
102  bool empty() const;
103 
104  bool repeatable() const
105  {
106  return !first_time_only_;
107  }
108 
109  // Normally non-serializable events are skipped when serializing (with a warning).
110  // If include_nonserializable is true, the game attempts to serialize them anyway.
111  // This will produce output that kind of looks like the event but would not deserialize to the same event.
112  void write_config(config& cfg, bool include_nonserializable = false) const;
113 
114  void set_repeatable(bool repeat = true)
115  {
116  first_time_only_ = !repeat;
117  }
118 
119  void set_priority(double priority)
120  {
122  }
123  void set_menu_item(bool imi)
124  {
125  is_menu_item_ = imi;
126  }
127 
128  void set_arguments(const config& cfg)
129  {
130  args_ = cfg;
131  }
132 
133  void read_filters(const config& cfg);
134  void add_filter(std::unique_ptr<event_filter>&& filter);
135 
137  void set_event_ref(int idx, bool has_preloaded);
138 
139 private:
142  bool disabled_;
143  /**
144  * Tracks whether the event was registered from the Lua API.
145  * This allows a warning to be issued in cases that will break saved games.
146  */
147  bool is_lua_;
148  /**
149  * Tracks whether the event was registered before or after the Lua preload event fired.
150  * This allows a warning to be issued in cases that will break saved games.
151  *
152  * Rationale: Events where the filter or action is a Lua function cannot be serialized.
153  * Therefore, if a saved game relies on it being serialized, it will fail.
154  * Events registered during or before preload do not need to be serialized, because when
155  * a saved game is loaded, the preload event re-triggers and re-registers the event.
156  * This is actually a common use-case for the Lua events API.
157  * So, this flag allows avoiding false positives in the warning message.
158  */
161  double priority_;
163  std::vector<std::shared_ptr<event_filter>> filters_;
164  std::string id_, types_;
165 };
166 
167 }
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:159
void set_arguments(const config &cfg)
Definition: handlers.hpp:128
bool has_preloaded_
Tracks whether the event was registered before or after the Lua preload event fired.
Definition: handlers.hpp:159
void register_wml_event(game_lua_kernel &lk)
Definition: handlers.cpp:378
void add_filter(std::unique_ptr< event_filter > &&filter)
Definition: handlers.cpp:373
void read_filters(const config &cfg)
Definition: handlers.cpp:358
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:383
void set_menu_item(bool imi)
Definition: handlers.hpp:123
void set_priority(double priority)
Definition: handlers.hpp:119
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:147
const std::string & names_raw() const
Definition: handlers.hpp:59
std::vector< std::shared_ptr< event_filter > > filters_
Definition: handlers.hpp:163
const double & priority() const
Definition: handlers.hpp:97
void set_repeatable(bool repeat=true)
Definition: handlers.hpp:114
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:173
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:178
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