Using Preferences

Preferences are small bits of global data which need to survive across invocations of the application. They may include things like registration information, the name of the last file that was opened, or the color the main screen is to be drawn in.

The XGPreferences class wrappers this functionality in a portable manner. It's not meant as a replacement for the host file system or for storing lots of data. It's simply a mechanism for storing simple "environment" associations.

A preference item is fundamentally an association between a 'variable' name and a 'value', which could either be an integer, a string or a boolean value. Preferences are generally read in on startup, modified in dialog boxes by the user, and written out when they are changed or when the application terminates.

Using the XGPreferences Class

The XGPreferences class, defined in <XPreferences.h>, defines a stack-based class which opens the preferences file for reading or writing. Preferences are then loaded in or saved once the preferences object has been constructed.

For example, to save your preferences to a preferences file, you would write:

>     void WritePreferences(void)
>     {
>         XGPreferences prefs(".MyAppRC");
>         prefs.SetBoolean("FirstBool",GFirstBool);
>         prefs.SetInteger("SecondValue",GSecondValue);
>     }

This writes two preferences items to the preferences file ".MyAppRC". (This assumes the code above is compiled on X. Microsoft Windows and MacOS uses different parameters in the constructor.

The XGPreferences Class

Constructors/Destructors:

> XGPreferences::XGPreferences(char *name, long creator);
> XGPreferences::XGPreferences(char *company, char *product, char *version);
> XGPreferences::XGPreferences(char *name);
> XGPreferences::~XGPreferences();

Getting and Setting Values:

> bool XGPreferences::GetBoolean(char *key);
> long XGPreferences::GetInteger(char *key);
> void XGPreferences::GetString(char *key, char *value);

> void XGPreferences::SetBoolean(char *key, bool value);
> void XGPreferences::SetInteger(char *key, long value);
> void XGPreferences::SetString(char *key, char *value);

Key Maintanance

> void XGPreferences::DeleteValue(char *key);

Constructors/Destructors:

> XGPreferences::XGPreferences(char *name, long type);

> > Macintosh: This is the Macintosh version of the preferences constructor. This creates a file by the specified name in the Preferences folder of the System Folder on the system the application is running on. Preferences folders should end with the word "Preferences": for example, "World Calendar Preferences" or "BugLink Preferences". (Of course not all applications stick to this rule. But it is what Apple recommends.)

> > The file type that is created is 'pref', and the creator of the file is specified in the 'creator' parameter above.

> XGPreferences::XGPreferences(char *company, char *product, char *version);

> > Microsoft Windows: This is the Windows version of the preferences constructor. This opens a registry key in the Windows 95/Windows NT system registry under /HKEY_LOCAL_MACHINE/SOFTWARE/company/product/version, as recommended by Microsoft. (The company name should be a one word name of your company, such as "PandaWave". The product name is the name of the application you are building. And version should be the version of the preferences data, not the application version, which you are saving. (This allows you to have multiple application versions with slightly different keys.)

> XGPreferences::XGPreferences(char *name);

> > X: This is the Unix version of the preferences constructor. This opens a preferences file in the home directory of the current user, saving the keys as text strings in that preferences file.

> XGPreferences::~XGPreferences();

> > This closes the preference file, flushing the key cache to the preferences file. (On the Macintosh and on X this maintains an internal 'cache' of values for fast access and updating of keys.)

Getting and Setting Values:

> bool XGPreferences::GetBoolean(char *key);

> > Gets the specified key value as a boolean value. Booleans are stored in the file as the text string "true" or "false". If a key does not exist with the specified name, this returns false.

> long XGPreferences::GetInteger(char *key);

> > Get the specified key value as an integer value. If a key does not exist, this returns 0.

> void XGPreferences::GetString(char *key, char *value);

> > Gets the specified key as a string. If a key does not exist, this returns the empty string.

> void XGPreferences::SetBoolean(char *key, bool value);

> > Creates or replaces an existing key with the specified boolean value.

> void XGPreferences::SetInteger(char *key, long value);

> > Creates or replaces an existing key with the specified integer value.

> void XGPreferences::SetString(char *key, char *value);

> > Creates or replaces an existing key with the specified string.

Key Maintanance:

> void XGPreferences::DeleteValue(char *key);

> > This deletes the specified key from the cache or from the registry file.