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_lua_kernel;
32 class variable_set;
33 
34 namespace game_events
35 {
36 struct queued_event;
37 /** Represents a single filter condition on an event. */
38 struct event_filter {
39  /** Runs the filter and returns whether it passes on the given event. */
40  virtual bool operator()(const queued_event& event_info) const = 0;
41  /** Serializes the filter into a config, if possible. */
42  virtual void serialize(config& cfg) const;
43  /** Returns true if it is possible to serialize the filter into a config. */
44  virtual bool can_serialize() const;
45  virtual ~event_filter() = default;
46  event_filter() = default;
47 private:
48  event_filter(const event_filter&) = delete;
49  event_filter& operator=(const event_filter&) = delete;
50 };
51 
53 {
54 public:
55  event_handler(const std::string& types, const std::string& id = "");
56 
57  std::vector<std::string> names(const variable_set* vars) const;
58  const std::string& names_raw() const
59  {
60  return types_;
61  }
62 
63  bool disabled() const
64  {
65  return disabled_;
66  }
67 
68  bool is_menu_item() const
69  {
70  return is_menu_item_;
71  }
72 
73  /** Flag this handler as disabled. */
74  void disable();
75 
76  /**
77  * Handles the queued event, according to our WML instructions.
78  *
79  * @param[in] event_info Information about the event that needs handling.
80  * @param[in] lk The lua kernel to run the WML command.
81  */
82  void handle_event(const queued_event& event_info, game_lua_kernel& lk);
83 
84  bool filter_event(const queued_event& event_info) const;
85 
86  const config& arguments() const
87  {
88  return args_;
89  }
90 
91  const std::string& id() const
92  {
93  return id_;
94  }
95 
96  const double& priority() const
97  {
98  return priority_;
99  }
100 
101  bool empty() const;
102 
103  bool repeatable() const
104  {
105  return !first_time_only_;
106  }
107 
108  // Normally non-serializable events are skipped when serializing (with a warning).
109  // If include_nonserializable is true, the game attempts to serialize them anyway.
110  // This will produce output that kind of looks like the event but would not deserialize to the same event.
111  void write_config(config& cfg, bool include_nonserializable = false) const;
112 
113  void set_repeatable(bool repeat = true)
114  {
115  first_time_only_ = !repeat;
116  }
117 
118  void set_priority(double priority)
119  {
121  }
122  void set_menu_item(bool imi)
123  {
124  is_menu_item_ = imi;
125  }
126 
127  void set_arguments(const config& cfg)
128  {
129  args_ = cfg;
130  }
131 
132  void read_filters(const config& cfg);
133  void add_filter(std::unique_ptr<event_filter>&& filter);
134 
136  void set_event_ref(int idx, bool has_preloaded);
137 
138 private:
141  bool disabled_;
142  /**
143  * Tracks whether the event was registered from the Lua API.
144  * This allows a warning to be issued in cases that will break saved games.
145  */
146  bool is_lua_;
147  /**
148  * Tracks whether the event was registered before or after the Lua preload event fired.
149  * This allows a warning to be issued in cases that will break saved games.
150  *
151  * Rationale: Events where the filter or action is a Lua function cannot be serialized.
152  * Therefore, if a saved game relies on it being serialized, it will fail.
153  * Events registered during or before preload do not need to be serialized, because when
154  * a saved game is loaded, the preload event re-triggers and re-registers the event.
155  * This is actually a common use-case for the Lua events API.
156  * So, this flag allows avoiding false positives in the warning message.
157  */
160  double priority_;
162  std::vector<std::shared_ptr<event_filter>> filters_;
163  std::string id_, types_;
164 };
165 
166 }
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:127
bool has_preloaded_
Tracks whether the event was registered before or after the Lua preload event fired.
Definition: handlers.hpp:158
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:91
std::vector< std::string > names(const variable_set *vars) const
Definition: handlers.cpp:64
const config & arguments() const
Definition: handlers.hpp:86
void set_event_ref(int idx, bool has_preloaded)
Definition: handlers.cpp:383
void set_menu_item(bool imi)
Definition: handlers.hpp:122
void set_priority(double priority)
Definition: handlers.hpp:118
bool is_menu_item() const
Definition: handlers.hpp:68
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:146
const std::string & names_raw() const
Definition: handlers.hpp:58
std::vector< std::shared_ptr< event_filter > > filters_
Definition: handlers.hpp:162
const double & priority() const
Definition: handlers.hpp:96
void set_repeatable(bool repeat=true)
Definition: handlers.hpp:113
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:38
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