tsc_AppSettings

This class provides a way for the plugin to persist application global settings as name-value pairs. These settings can be stored, retrieved, and changed by the plugin, but are not visible to other plugins.  All functions are static; Survey Core has only one settings object.

A setting is one simple value type, a string, or a list of strings, with an associated name known as the key.  

Keys may contain most ASCII characters except for control characters.  It's a convention to avoid special characters and use dot-separated C++ names to make up a key, with the most significant first, such as "Stakeout.HorizAngle.Tolerance".

To avoid name clashes, each plugin's keys are given a unique prefix. This of course prevents inter-plugin communications by this means.

All values are converted to strings for storing.  This means it's possible that a double value stored and retrieved again may differ from the original by a tiny rounding amount.  String values must avoid binary data, and in particular, control characters from \x00 to \x1F. Suggested workarounds include using something like base-64 encoding.

tsc_AppSettings is not designed to store large amounts of data; keep sizes below a few hundreds of bytes per key and avoid adding more than a few tens of keys.

New and updated values are not written instantly, but are flushed periodically as well as at shutdown.

Be aware that the stored values can be lost and may be discarded when the Survey Core install is upgraded.  Mission critical settings should be stored elsewhere.

Methods

Returns true if the given key exists in the settings.
static bool Exists (const char* key);

These functions get an existing setting's value, or if the setting is not present they return the supplied default, or in the case of tsc_StringList, an empty list.

static tsc_String     Get (const char* key, const char* default);
static tsc_StringList Get (const char* key);
static int            Get (const char* key, int default);
static unsigned int   Get (const char* key, unsigned int default);
static double         Get (const char* key, double default);
static bool           Get (const char* key, bool default);

These functions set or replace a key's value with the supplied value.  The type of the new value is not restricted to the type of the value being replaced, though it is usually a good idea to use a consistent type for every value.

static void   Set (const char* key, const char* value);
static void   Set (const char* key, const tsc_StringList& values);
static void   Set (const char* key, int value);
static void   Set (const char* key, unsigned int value);
static void   Set (const char* key, double value);
static void   Set (const char* key, bool value);