src/settings_internal.h

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 /** @file settings_internal.h Functions and types used internally for the settings configurations. */
   9
  10 #ifndef SETTINGS_INTERNAL_H
  11 #define SETTINGS_INTERNAL_H
  12
  13 #include <variant>
  14 #include "saveload/saveload.h"
  15
  16 enum SettingFlag : uint16_t {
  17         SF_NONE = 0,
  18         SF_GUI_0_IS_SPECIAL        = 1 <<  0, ///< A value of zero is possible and has a custom string (the one after "strval").
  19         SF_GUI_DROPDOWN            = 1 <<  2, ///< The value represents a limited number of string-options (internally integer) presented as dropdown.
  20         SF_GUI_CURRENCY            = 1 <<  3, ///< The number represents money, so when reading value multiply by exchange rate.
  21         SF_NETWORK_ONLY            = 1 <<  4, ///< This setting only applies to network games.
  22         SF_NO_NETWORK              = 1 <<  5, ///< This setting does not apply to network games; it may not be changed during the game.
  23         SF_NEWGAME_ONLY            = 1 <<  6, ///< This setting cannot be changed in a game.
  24         SF_SCENEDIT_TOO            = 1 <<  7, ///< This setting can be changed in the scenario editor (only makes sense when SF_NEWGAME_ONLY is set).
  25         SF_SCENEDIT_ONLY           = 1 <<  8, ///< This setting can only be changed in the scenario editor.
  26         SF_PER_COMPANY             = 1 <<  9, ///< This setting can be different for each company (saved in company struct).
  27         SF_NOT_IN_SAVE             = 1 << 10, ///< Do not save with savegame, basically client-based.
  28         SF_NOT_IN_CONFIG           = 1 << 11, ///< Do not save to config file.
  29         SF_NO_NETWORK_SYNC         = 1 << 12, ///< Do not synchronize over network (but it is saved if SF_NOT_IN_SAVE is not set).
  30 };
  31 DECLARE_ENUM_AS_BIT_SET(SettingFlag)
  32
  33 /**
  34  * A SettingCategory defines a grouping of the settings.
  35  * The group #SC_BASIC is intended for settings which also a novice player would like to change and is able to understand.
  36  * The group #SC_ADVANCED is intended for settings which an experienced player would like to use. This is the case for most settings.
  37  * Finally #SC_EXPERT settings only few people want to see in rare cases.
  38  * The grouping is meant to be inclusive, i.e. all settings in #SC_BASIC also will be included
  39  * in the set of settings in #SC_ADVANCED. The group #SC_EXPERT contains all settings.
  40  */
  41 enum SettingCategory {
  42         SC_NONE = 0,
  43
  44         /* Filters for the list */
  45         SC_BASIC_LIST      = 1 << 0,    ///< Settings displayed in the list of basic settings.
  46         SC_ADVANCED_LIST   = 1 << 1,    ///< Settings displayed in the list of advanced settings.
  47         SC_EXPERT_LIST     = 1 << 2,    ///< Settings displayed in the list of expert settings.
  48
  49         /* Setting classification */
  50         SC_BASIC           = SC_BASIC_LIST | SC_ADVANCED_LIST | SC_EXPERT_LIST,  ///< Basic settings are part of all lists.
  51         SC_ADVANCED        = SC_ADVANCED_LIST | SC_EXPERT_LIST,                  ///< Advanced settings are part of advanced and expert list.
  52         SC_EXPERT          = SC_EXPERT_LIST,                                     ///< Expert settings can only be seen in the expert list.
  53
  54         SC_END,
  55 };
  56
  57 /**
  58  * Type of settings for filtering.
  59  */
  60 enum SettingType {
  61         ST_GAME,      ///< Game setting.
  62         ST_COMPANY,   ///< Company setting.
  63         ST_CLIENT,    ///< Client setting.
  64
  65         ST_ALL,       ///< Used in setting filter to match all types.
  66 };
  67
  68 struct IniItem;
  69
  70 /** Properties of config file settings. */
  71 struct SettingDesc {
  72         SettingDesc(const SaveLoad &save, SettingFlag flags, bool startup) :
  73                 flags(flags), startup(startup), save(save) {}
  74         virtual ~SettingDesc() = default;
  75
  76         SettingFlag flags;  ///< Handles how a setting would show up in the GUI (text/currency, etc.).
  77         bool startup;       ///< Setting has to be loaded directly at startup?.
  78         SaveLoad save;      ///< Internal structure (going to savegame, parts to config).
  79
  80         bool IsEditable(bool do_command = false) const;
  81         SettingType GetType() const;
  82
  83         /**
  84          * Get the name of this setting.
  85          * @return The name of the setting.
  86          */
  87         constexpr const std::string &GetName() const
  88         {
  89                 return this->save.name;
  90         }
  91
  92         /**
  93          * Check whether this setting is an integer type setting.
  94          * @return True when the underlying type is an integer.
  95          */
  96         virtual bool IsIntSetting() const { return false; }
  97
  98         /**
  99          * Check whether this setting is an string type setting.
 100          * @return True when the underlying type is a string.
 101          */
 102         virtual bool IsStringSetting() const { return false; }
 103
 104         const struct IntSettingDesc *AsIntSetting() const;
 105         const struct StringSettingDesc *AsStringSetting() const;
 106
 107         /**
 108          * Format the value of the setting associated with this object.
 109          * @param buf The before of the buffer to format into.
 110          * @param last The end of the buffer to format into.
 111          * @param object The object the setting is in.
 112          */
 113         virtual std::string FormatValue(const void *object) const = 0;
 114
 115         /**
 116          * Parse/read the value from the Ini item into the setting associated with this object.
 117          * @param item The Ini item with the content of this setting.
 118          * @param object The object the setting is in.
 119          */
 120         virtual void ParseValue(const IniItem *item, void *object) const = 0;
 121
 122         /**
 123          * Check whether the value in the Ini item is the same as is saved in this setting in the object.
 124          * It might be that determining whether the value is the same is way more expensive than just
 125          * writing the value. In those cases this function may unconditionally return false even though
 126          * the value might be the same as in the Ini item.
 127          * @param item The Ini item with the content of this setting.
 128          * @param object The object the setting is in.
 129          * @return True if the value is definitely the same (might be false when the same).
 130          */
 131         virtual bool IsSameValue(const IniItem *item, void *object) const = 0;
 132
 133         /**
 134          * Check whether the value is the same as the default value.
 135          *
 136          * @param object The object the setting is in.
 137          * @return true iff the value is the default value.
 138          */
 139         virtual bool IsDefaultValue(void *object) const = 0;
 140 };
 141
 142 /** Base integer type, including boolean, settings. Only these are shown in the settings UI. */
 143 struct IntSettingDesc : SettingDesc {
 144         typedef StringID GetTitleCallback(const IntSettingDesc &sd);
 145         typedef StringID GetHelpCallback(const IntSettingDesc &sd);
 146         typedef void SetValueDParamsCallback(const IntSettingDesc &sd, uint first_param, int32_t value);
 147
 148         /**
 149          * A check to be performed before the setting gets changed. The passed integer may be
 150          * changed by the check if that is important, for example to remove some unwanted bit.
 151          * The return value denotes whether the value, potentially after the changes,
 152          * is allowed to be used/set in the configuration.
 153          * @param value The prospective new value for the setting.
 154          * @return True when the setting is accepted.
 155          */
 156         typedef bool PreChangeCheck(int32_t &value);
 157         /**
 158          * A callback to denote that a setting has been changed.
 159          * @param The new value for the setting.
 160          */
 161         typedef void PostChangeCallback(int32_t value);
 162
 163         template <
 164                 typename Tdef,
 165                 typename Tmin,
 166                 typename Tmax,
 167                 typename Tinterval,
 168                 std::enable_if_t<std::disjunction_v<std::is_convertible<Tdef, int32_t>, std::is_base_of<StrongTypedefBase, Tdef>>, int> = 0,
 169                 std::enable_if_t<std::disjunction_v<std::is_convertible<Tmin, int32_t>, std::is_base_of<StrongTypedefBase, Tmin>>, int> = 0,
 170                 std::enable_if_t<std::disjunction_v<std::is_convertible<Tmax, uint32_t>, std::is_base_of<StrongTypedefBase, Tmax>>, int> = 0,
 171                 std::enable_if_t<std::disjunction_v<std::is_convertible<Tinterval, int32_t>, std::is_base_of<StrongTypedefBase, Tinterval>>, int> = 0
 172         >
 173         IntSettingDesc(const SaveLoad &save, SettingFlag flags, bool startup, Tdef def,
 174                         Tmin min, Tmax max, Tinterval interval, StringID str, StringID str_help, StringID str_val,
 175                         SettingCategory cat, PreChangeCheck pre_check, PostChangeCallback post_callback,
 176                         GetTitleCallback get_title_cb, GetHelpCallback get_help_cb, SetValueDParamsCallback set_value_dparams_cb) :
 177                 SettingDesc(save, flags, startup),
 178                         str(str), str_help(str_help), str_val(str_val), cat(cat), pre_check(pre_check),
 179                         post_callback(post_callback),
 180                         get_title_cb(get_title_cb), get_help_cb(get_help_cb), set_value_dparams_cb(set_value_dparams_cb) {
 181                 if constexpr (std::is_base_of_v<StrongTypedefBase, Tdef>) {
 182                         this->def = def.base();
 183                 } else {
 184                         this->def = def;
 185                 }
 186
 187                 if constexpr (std::is_base_of_v<StrongTypedefBase, Tmin>) {
 188                         this->min = min.base();
 189                 } else {
 190                         this->min = min;
 191                 }
 192
 193                 if constexpr (std::is_base_of_v<StrongTypedefBase, Tmax>) {
 194                         this->max = max.base();
 195                 } else {
 196                         this->max = max;
 197                 }
 198
 199                 if constexpr (std::is_base_of_v<StrongTypedefBase, Tinterval>) {
 200                         this->interval = interval.base();
 201                 } else {
 202                         this->interval = interval;
 203                 }
 204         }
 205
 206         int32_t def;              ///< default value given when none is present
 207         int32_t min;              ///< minimum values
 208         uint32_t max;             ///< maximum values
 209         int32_t interval;         ///< the interval to use between settings in the 'settings' window. If interval is '0' the interval is dynamically determined
 210         StringID str;           ///< (translated) string with descriptive text; gui and console
 211         StringID str_help;      ///< (Translated) string with help text; gui only.
 212         StringID str_val;       ///< (Translated) first string describing the value.
 213         SettingCategory cat;    ///< assigned categories of the setting
 214         PreChangeCheck *pre_check;         ///< Callback to check for the validity of the setting.
 215         PostChangeCallback *post_callback; ///< Callback when the setting has been changed.
 216         GetTitleCallback *get_title_cb;
 217         GetHelpCallback *get_help_cb;
 218         SetValueDParamsCallback *set_value_dparams_cb;
 219
 220         StringID GetTitle() const;
 221         StringID GetHelp() const;
 222         void SetValueDParams(uint first_param, int32_t value) const;
 223
 224         /**
 225          * Check whether this setting is a boolean type setting.
 226          * @return True when the underlying type is an integer.
 227          */
 228         virtual bool IsBoolSetting() const { return false; }
 229         bool IsIntSetting() const override { return true; }
 230
 231         void ChangeValue(const void *object, int32_t newvalue) const;
 232         void MakeValueValidAndWrite(const void *object, int32_t value) const;
 233
 234         virtual size_t ParseValue(const char *str) const;
 235         std::string FormatValue(const void *object) const override;
 236         void ParseValue(const IniItem *item, void *object) const override;
 237         bool IsSameValue(const IniItem *item, void *object) const override;
 238         bool IsDefaultValue(void *object) const override;
 239         int32_t Read(const void *object) const;
 240
 241 private:
 242         void MakeValueValid(int32_t &value) const;
 243         void Write(const void *object, int32_t value) const;
 244 };
 245
 246 /** Boolean setting. */
 247 struct BoolSettingDesc : IntSettingDesc {
 248         BoolSettingDesc(const SaveLoad &save, SettingFlag flags, bool startup, bool def,
 249                         StringID str, StringID str_help, StringID str_val, SettingCategory cat,
 250                         PreChangeCheck pre_check, PostChangeCallback post_callback,
 251                         GetTitleCallback get_title_cb, GetHelpCallback get_help_cb, SetValueDParamsCallback set_value_dparams_cb) :
 252                 IntSettingDesc(save, flags, startup, def ? 1 : 0, 0, 1, 0, str, str_help, str_val, cat,
 253                         pre_check, post_callback, get_title_cb, get_help_cb, set_value_dparams_cb) {}
 254
 255         static std::optional<bool> ParseSingleValue(const char *str);
 256
 257         bool IsBoolSetting() const override { return true; }
 258         size_t ParseValue(const char *str) const override;
 259         std::string FormatValue(const void *object) const override;
 260 };
 261
 262 /** One of many setting. */
 263 struct OneOfManySettingDesc : IntSettingDesc {
 264         typedef size_t OnConvert(const char *value); ///< callback prototype for conversion error
 265
 266         OneOfManySettingDesc(const SaveLoad &save, SettingFlag flags, bool startup, int32_t def,
 267                         int32_t max, StringID str, StringID str_help, StringID str_val, SettingCategory cat,
 268                         PreChangeCheck pre_check, PostChangeCallback post_callback,
 269                         GetTitleCallback get_title_cb, GetHelpCallback get_help_cb, SetValueDParamsCallback set_value_dparams_cb,
 270                         std::initializer_list<const char *> many, OnConvert *many_cnvt) :
 271                 IntSettingDesc(save, flags, startup, def, 0, max, 0, str, str_help, str_val, cat,
 272                         pre_check, post_callback, get_title_cb, get_help_cb, set_value_dparams_cb), many_cnvt(many_cnvt)
 273         {
 274                 for (auto one : many) this->many.push_back(one);
 275         }
 276
 277         std::vector<std::string> many; ///< possible values for this type
 278         OnConvert *many_cnvt;          ///< callback procedure when loading value mechanism fails
 279
 280         static size_t ParseSingleValue(const char *str, size_t len, const std::vector<std::string> &many);
 281         std::string FormatSingleValue(uint id) const;
 282
 283         size_t ParseValue(const char *str) const override;
 284         std::string FormatValue(const void *object) const override;
 285 };
 286
 287 /** Many of many setting. */
 288 struct ManyOfManySettingDesc : OneOfManySettingDesc {
 289         ManyOfManySettingDesc(const SaveLoad &save, SettingFlag flags, bool startup,
 290                 int32_t def, StringID str, StringID str_help, StringID str_val, SettingCategory cat,
 291                 PreChangeCheck pre_check, PostChangeCallback post_callback,
 292                 GetTitleCallback get_title_cb, GetHelpCallback get_help_cb, SetValueDParamsCallback set_value_dparams_cb,
 293                 std::initializer_list<const char *> many, OnConvert *many_cnvt) :
 294                 OneOfManySettingDesc(save, flags, startup, def, (1 << many.size()) - 1, str, str_help,
 295                         str_val, cat, pre_check, post_callback, get_title_cb, get_help_cb, set_value_dparams_cb, many, many_cnvt) {}
 296
 297         size_t ParseValue(const char *str) const override;
 298         std::string FormatValue(const void *object) const override;
 299 };
 300
 301 /** String settings. */
 302 struct StringSettingDesc : SettingDesc {
 303         /**
 304          * A check to be performed before the setting gets changed. The passed string may be
 305          * changed by the check if that is important, for example to remove unwanted white
 306          * space. The return value denotes whether the value, potentially after the changes,
 307          * is allowed to be used/set in the configuration.
 308          * @param value The prospective new value for the setting.
 309          * @return True when the setting is accepted.
 310          */
 311         typedef bool PreChangeCheck(std::string &value);
 312         /**
 313          * A callback to denote that a setting has been changed.
 314          * @param The new value for the setting.
 315          */
 316         typedef void PostChangeCallback(const std::string &value);
 317
 318         StringSettingDesc(const SaveLoad &save, SettingFlag flags, bool startup, const char *def,
 319                         uint32_t max_length, PreChangeCheck pre_check, PostChangeCallback post_callback) :
 320                 SettingDesc(save, flags, startup), def(def == nullptr ? "" : def), max_length(max_length),
 321                         pre_check(pre_check), post_callback(post_callback) {}
 322
 323         std::string def;                   ///< Default value given when none is present
 324         uint32_t max_length;                 ///< Maximum length of the string, 0 means no maximum length
 325         PreChangeCheck *pre_check;         ///< Callback to check for the validity of the setting.
 326         PostChangeCallback *post_callback; ///< Callback when the setting has been changed.
 327
 328         bool IsStringSetting() const override { return true; }
 329         void ChangeValue(const void *object, std::string &newval) const;
 330
 331         std::string FormatValue(const void *object) const override;
 332         void ParseValue(const IniItem *item, void *object) const override;
 333         bool IsSameValue(const IniItem *item, void *object) const override;
 334         bool IsDefaultValue(void *object) const override;
 335         const std::string &Read(const void *object) const;
 336
 337 private:
 338         void MakeValueValid(std::string &str) const;
 339         void Write(const void *object, const std::string &str) const;
 340 };
 341
 342 /** List/array settings. */
 343 struct ListSettingDesc : SettingDesc {
 344         ListSettingDesc(const SaveLoad &save, SettingFlag flags, bool startup, const char *def) :
 345                 SettingDesc(save, flags, startup), def(def) {}
 346
 347         const char *def;        ///< default value given when none is present
 348
 349         std::string FormatValue(const void *object) const override;
 350         void ParseValue(const IniItem *item, void *object) const override;
 351         bool IsSameValue(const IniItem *item, void *object) const override;
 352         bool IsDefaultValue(void *object) const override;
 353 };
 354
 355 /** Placeholder for settings that have been removed, but might still linger in the savegame. */
 356 struct NullSettingDesc : SettingDesc {
 357         NullSettingDesc(const SaveLoad &save) :
 358                 SettingDesc(save, SF_NOT_IN_CONFIG, false) {}
 359
 360         std::string FormatValue(const void *) const override { NOT_REACHED(); }
 361         void ParseValue(const IniItem *, void *) const override { NOT_REACHED(); }
 362         bool IsSameValue(const IniItem *, void *) const override { NOT_REACHED(); }
 363         bool IsDefaultValue(void *) const override { NOT_REACHED(); }
 364 };
 365
 366 typedef std::variant<IntSettingDesc, BoolSettingDesc, OneOfManySettingDesc, ManyOfManySettingDesc, StringSettingDesc, ListSettingDesc, NullSettingDesc> SettingVariant;
 367
 368 /**
 369  * Helper to convert the type of the iterated settings description to a pointer to it.
 370  * @param desc The type of the iterator of the value in SettingTable.
 371  * @return The actual pointer to SettingDesc.
 372  */
 373 static constexpr const SettingDesc *GetSettingDesc(const SettingVariant &desc)
 374 {
 375         return std::visit([](auto&& arg) -> const SettingDesc * { return &arg; }, desc);
 376 }
 377
 378 typedef std::span<const SettingVariant> SettingTable;
 379
 380 const SettingDesc *GetSettingFromName(const std::string_view name);
 381 void GetSaveLoadFromSettingTable(SettingTable settings, std::vector<SaveLoad> &saveloads);
 382 bool SetSettingValue(const IntSettingDesc *sd, int32_t value, bool force_newgame = false);
 383 bool SetSettingValue(const StringSettingDesc *sd, const std::string value, bool force_newgame = false);
 384
 385 #endif /* SETTINGS_INTERNAL_H */