[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5.3 Configuration Domains

Written by Eric Sunshine, sunshine@sunshineco.com.

When you run an application, the configuration manager collects configuration information from various locations, including information loaded from the application's own configuration file and those of plugin modules. It is possible that configuration information gathered from various locations can contain conflicting configuration settings. For this reason, a priority value is assigned configuration information from each source, and the priority value is used to resolve conflicts.

Priorities are assigned to configuration information based upon the following heuristic. Highest priority sources (known as domains) are listed first; lowest priority sources are listed last.

If the program allows the user to change options and settings, these changes are applied to the user-specific, application-specific domain by default. It is possible programmatically to change settings in other domains, but this is rarely useful or needed since most user settings belong in the user-specific, application-specific domain.

Platform-Specific Per-User Settings Storage

When programs store settings for a particular user, those settings belong to that user, which means that the settings must be stored separately from settings of other users. Furthermore, it is often convenient and desirable for a user's settings to roam with the user as the user moves from machine to machine. In order to satisfy these goals, Crystal Space utilizes platform-specific facilities for recording user-specific settings. Utilization of these facilities is typically transparent to both users and programmers, however an understanding of some basic issues regarding these facilities is useful.

Application Unique Identifier

As noted earlier, each application uses a unique identifier to distinguish its per-user settings from the per-user settings of other applications. An application typically sets its unique identifier via the `System.ApplicationID' key in its application-specific configuration file, though the identifier can also be set programmatically.

The actual manner in which the application identifier is employed to access and store settings is specific to each platform-dependent implementation, however it is a good idea to ensure that each application identifier is unique in order to avoid collisions with identifiers of other applications. For this reason, it is strongly recommended that an application identifier be composed with the form `<Producer>.<ProductName>'. Crystal Space example applications use `CrystalSpace' for the Producer portion of the application identifier; for example: `CrystalSpace.Walktest'. Your own application identifier can be composed of any suitable components. For instance, you might place the following key in your application-specific configuration file.

 
System.ApplicationID = MyCompany.MyGame

Windows User-Specific Settings

On Windows, user-specific settings are stored in configuration files in the `Application Data' directory. The exact location and name of this directory differs between Windows versions and from language to language. On Windows XP, 2000, and NT the directory is typically `C:\Documents and Settings\<username>\Application Data'. On on Win9x it is typically `C:\WINDOWS\Application Data'.

The actual path of the user-specific, application-specific configuration file is generated from the application's unique application identifier by replacing all dots ('.') with backslashes ('\') and adding a `.cfg' suffix. For example, the configuration for the application which has a unique identifier `MyGames.ClickFrenzy2' will be stored as `Application Data\MyGames\ClickFrenzy2.cfg'. User-specific, application-neutral settings, on the other hand, will be stored as `Application Data\CrystalSpace\Global.cfg'. The configuration file format is the described in the configuration file section, Configuration File.

Registry Storage

On Windows, it is also possible to store configuration settings in the Registry. This is accomplished by instantiating a `csWin32RegistryConfig' object and setting it as the configuration manager's dynamic domain after the configuration manager has been initialized. See the documentation for `csWin32RegistryConfig' for full details.

Unix User-Specific Settings

On Unix and Unix-like platforms, user-specific settings are stored in files in the hidden directory `$HOME/.crystalspace'. The actual name of a configuration file is generated from the unique application identifier with a `.cfg' suffix. For example, the configuration for the application which has a unique identifier `MyGames.ClickFrenzy2' will be stored as:

 
$HOME/.crystalspace/MyGames.ClickFrenzy2.cfg

User-specific, application-neutral settings, on the other hand, will be stored as `$HOME/.crystalspace/CrystalSpace.Global.cfg'. The configuration file format is described in the configuration file section, Configuration File.

MacOS/X User-Specific Settings

On MacOS/X, user-specific settings are stored via the Cocoa defaults database (also known programmatically as `NSUserDefaults'). A program's unique application identifier is used as the name of the persistent `NSUserDefaults' domain into which the settings are stored. For example, to list all the configuration settings for the application which has a unique identifier `MyGames.ClickFrenzy2', you would invoke the following command:

 
defaults read MyGames.ClickFrenzy2

User-specific, application-neutral settings, on the other hand, will be stored under the `NSUserDefaults' domain named `CrystalSpace.Global'. You can list the user-specific, application-neutral settings like this:

 
defaults read CrystalSpace.Global

If you want to set some configuration options for all Crystal Space applications you can do so by storing the settings in the `CrystalSpace.Global' domain. For instance, to instruct all programs to use resolution 1024x768, you could do this:

 
defaults write CrystalSpace.Global Video.ScreenWidth 1024
defaults write CrystalSpace.Global Video.ScreenHeight 768

These settings will be used by all Crystal Space-based applications unless overridden explicitly by command-line arguments or user-specific, application-specific settings.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated using texi2html 1.76.