src/settings_internal.h

   1 /* $Id: settings_internal.h 24900 2013-01-08 22:46:42Z planetmaker $ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * 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.
   6  * 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.
   7  * 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/>.
   8  */
   9
  10 /** @file settings_internal.h Functions and types used internally for the settings configurations. */
  11
  12 #ifndef SETTINGS_INTERNAL_H
  13 #define SETTINGS_INTERNAL_H
  14
  15 #include "saveload/saveload.h"
  16
  17 /**
  18  * Convention/Type of settings. This is then further specified if necessary
  19  * with the SLE_ (SLE_VAR/SLE_FILE) enums in saveload.h
  20  * @see VarTypes
  21  * @see SettingDescBase
  22  */
  23 enum SettingDescTypeLong {
  24         /* 4 bytes allocated a maximum of 16 types for GenericType */
  25         SDT_BEGIN       = 0,
  26         SDT_NUMX        = 0, ///< any number-type
  27         SDT_BOOLX       = 1, ///< a boolean number
  28         SDT_ONEOFMANY   = 2, ///< bitmasked number where only ONE bit may be set
  29         SDT_MANYOFMANY  = 3, ///< bitmasked number where MULTIPLE bits may be set
  30         SDT_INTLIST     = 4, ///< list of integers separated by a comma ','
  31         SDT_STRING      = 5, ///< string with a pre-allocated buffer
  32         SDT_END,
  33         /* 10 more possible primitives */
  34 };
  35 typedef SimpleTinyEnumT<SettingDescTypeLong, byte> SettingDescType;
  36
  37
  38 enum SettingGuiFlagLong {
  39         /* 1 byte allocated for a maximum of 8 flags
  40          * Flags directing saving/loading of a variable */
  41         SGF_NONE = 0,
  42         SGF_0ISDISABLED  = 1 << 0, ///< a value of zero means the feature is disabled
  43         SGF_DISPLAY_ABS  = 1 << 1, ///< display absolute value of the setting
  44         SGF_MULTISTRING  = 1 << 2, ///< the value represents a limited number of string-options (internally integer)
  45         SGF_NETWORK_ONLY = 1 << 3, ///< this setting only applies to network games
  46         SGF_CURRENCY     = 1 << 4, ///< the number represents money, so when reading value multiply by exchange rate
  47         SGF_NO_NETWORK   = 1 << 5, ///< this setting does not apply to network games; it may not be changed during the game
  48         SGF_NEWGAME_ONLY = 1 << 6, ///< this setting cannot be changed in a game
  49         SGF_SCENEDIT_TOO = 1 << 7, ///< this setting can be changed in the scenario editor (only makes sense when SGF_NEWGAME_ONLY is set)
  50         SGF_PER_COMPANY  = 1 << 8, ///< this setting can be different for each company (saved in company struct)
  51 };
  52 DECLARE_ENUM_AS_BIT_SET(SettingGuiFlagLong)
  53 typedef SimpleTinyEnumT<SettingGuiFlagLong, uint16> SettingGuiFlag;
  54
  55 /**
  56  * A SettingCategory defines a grouping of the settings.
  57  * The group #SC_BASIC is intended for settings which also a novice player would like to change and is able to understand.
  58  * The group #SC_ADVANCED is intended for settings which an experienced player would like to use. This is the case for most settings.
  59  * Finally #SC_EXPERT settings only few people want to see in rare cases.
  60  * The grouping is meant to be inclusive, i.e. all settings in #SC_BASIC also will be included
  61  * in the set of settings in #SC_ADVANCED. The group #SC_EXPERT contains all settings.
  62  */
  63 enum SettingCategory {
  64         SC_NONE = 0,
  65
  66         /* Filters for the list */
  67         SC_BASIC_LIST      = 1 << 0,    ///< Settings displayed in the list of basic settings.
  68         SC_ADVANCED_LIST   = 1 << 1,    ///< Settings displayed in the list of advanced settings.
  69         SC_EXPERT_LIST     = 1 << 2,    ///< Settings displayed in the list of expert settings.
  70
  71         /* Setting classification */
  72         SC_BASIC           = SC_BASIC_LIST | SC_ADVANCED_LIST | SC_EXPERT_LIST,  ///< Basic settings are part of all lists.
  73         SC_ADVANCED        = SC_ADVANCED_LIST | SC_EXPERT_LIST,                  ///< Advanced settings are part of advanced and expert list.
  74         SC_EXPERT          = SC_EXPERT_LIST,                                     ///< Expert settings can only be seen in the expert list.
  75
  76         SC_END,
  77 };
  78
  79 /**
  80  * Type of settings for filtering.
  81  */
  82 enum SettingType {
  83         ST_GAME,      ///< Game setting.
  84         ST_COMPANY,   ///< Company setting.
  85         ST_CLIENT,    ///< Client setting.
  86
  87         ST_ALL,       ///< Used in setting filter to match all types.
  88 };
  89
  90 typedef bool OnChange(int32 var);           ///< callback prototype on data modification
  91 typedef size_t OnConvert(const char *value); ///< callback prototype for conversion error
  92
  93 /** Properties of config file settings. */
  94 struct SettingDescBase {
  95         const char *name;       ///< name of the setting. Used in configuration file and for console
  96         const void *def;        ///< default value given when none is present
  97         SettingDescType cmd;    ///< various flags for the variable
  98         SettingGuiFlag flags;   ///< handles how a setting would show up in the GUI (text/currency, etc.)
  99         int32 min;              ///< minimum values
 100         uint32 max;             ///< maximum values
 101         int32 interval;         ///< the interval to use between settings in the 'settings' window. If interval is '0' the interval is dynamically determined
 102         const char *many;       ///< ONE/MANY_OF_MANY: string of possible values for this type
 103         StringID str;           ///< (translated) string with descriptive text; gui and console
 104         StringID str_help;      ///< (Translated) string with help text; gui only.
 105         StringID str_val;       ///< (Translated) first string describing the value.
 106         OnChange *proc;         ///< callback procedure for when the value is changed
 107         OnConvert *proc_cnvt;   ///< callback procedure when loading value mechanism fails
 108         SettingCategory cat;    ///< assigned categories of the setting
 109 };
 110
 111 struct SettingDesc {
 112         SettingDescBase desc;   ///< Settings structure (going to configuration file)
 113         SaveLoad save;          ///< Internal structure (going to savegame, parts to config)
 114
 115         bool IsEditable(bool do_command = false) const;
 116         SettingType GetType() const;
 117 };
 118
 119 /* NOTE: The only difference between SettingDesc and SettingDescGlob is
 120  * that one uses global variables as a source and the other offsets
 121  * in a struct which are bound to a certain variable during runtime.
 122  * The only way to differentiate between these two is to check if an object
 123  * has been passed to the function or not. If not, then it is a global variable
 124  * and save->variable has its address, otherwise save->variable only holds the
 125  * offset in a certain struct */
 126 typedef SettingDesc SettingDescGlobVarList;
 127
 128 const SettingDesc *GetSettingFromName(const char *name, uint *i);
 129 bool SetSettingValue(uint index, int32 value, bool force_newgame = false);
 130 bool SetSettingValue(uint index, const char *value, bool force_newgame = false);
 131 void SetCompanySetting(uint index, int32 value);
 132
 133 #endif /* SETTINGS_INTERNAL_H */