My "factory default" setting. At pre-init time, before we've loaded the settings file for the first time, we'll run through all SettingsItems and store their pre-defined source-code settings here, as though we were saving the values to a file. Later, when we load a file, if we find the file lacks an entry for this setting item, we'll simply re-load the factory default from this property.

Should this item be included in listings shown to the user? If this is true, the UI will include this setting in a display list of current settings shown to the user on request, by calling our settingDesc method.

Display a message fragment that shows the current setting value. We use this to show the player exactly what we're saving or restoring in response to a SAVE DEFAULTS or RESTORE DEFAULTS command, so that there's no confusion about which settings are included. In most cases, the best thing to show here is the command that selects the current setting: "NOTIFY ON," for example. This is for the UI's convenience; it's not used by the settings manager itself.

The setting's identifier string. This is the ID of the setting as it appears in the external configuration file.

The ID should be chosen to ensure uniqueness. To reduce the chances of name collisions, we suggest a convention of using a two part name: a prefix identifying the source of the name (an abbreviated version of the name of the library, library extension, or game), followed by a period as a separator, followed by a short descriptive name for the variable. The library follows this convention by using names of the form "adv3.xxx" - the "adv3" prefix indicates the standard library.

The ID should contain only letters, numbers, and periods. Don't use spaces or punctuation marks (other than periods).

Note that the ID string is for the program's use, not the player's, so this isn't something we translate to different languages. Note, though, that the configuration file is a simple text file, so it wouldn't hurt to use a reasonably meaningful name, in case the user takes it upon herself to look at the contents of the file.

Load from a settings file. By default, this simply calls the setting file object to load the data.

This implementation is suitable for any scalar type, so this won't need to be overwritten for subclasses that only need to load a single string value from the file. Subclasses that implement complex (non-scalar) datatypes can override this as needed to read multiple line items from the file.

Save to a settings file. By default, this makes a string out of our value and updates or adds our corresponding entry in the file.

This implementation is suitable for any scalar type, so this won't need to be overwritten for subclasses that only need to store a single string value in the file. Subclasses that implement complex (non-scalar) datatypes can override this as needed to manipulate multiple line items in the file.

Set the current value to the contents of the given string. The string contains a textual representation of a setting value, as previously generated with settingToText().

This is only needed if the default restoreItem() method is used.

Get the textual representation of the setting - returns a string representing the setting as it should appear in the external configuration file. We use this to write the setting to the file.

Note that this is only needed if the default saveItem() method is used.