4.5.3 Configuration Domains

Written by Eric Sunshine, [email protected].

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.

• Command-line options are given the highest priority. They override settings which appear in configuration files. For example, the `--video=' option will override the `System.Plugins.iGraphics3D' key in all configuration files.
• User-specific, application-specific settings exists at the next highest priority. These are settings specific to a particular user and specific to a particular application. This is the place where a user's personal settings are stored by a program. For example, if a game allows a user to choose screen resolution, or if it wants to store statistics about the user, it would store that information in this domain. Such information is specific to a particular user of this particular application. Such information is not relevant to other users or other applications.

  Settings at this priority are stored in a platform-dependent fashion (see Config PerUser). Often, these settings roam with a user automatically as the user moves from machine to machine.

  In order to associate settings with itself, an application needs to provide the configuration manager with a unique identifier. Typically, this is accomplished by placing a `System.ApplicationID' key in the application's own configuration file. It can also be set programmatically. Given an application's identifer, the configuration manager can locate the user-specific settings associated with that application.

  It is recommended that you use the form `<Producer>.<ProductName>' when constructing an application identifier. 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

• User-specific, application-neutral settings have the next highest priority. These are settings which are specific to a particular user, but which are not specific to any particular application. For instance, a user might prefer to use full-screen mode with all Crystal Space-derived applications, in which case he can give the `Video.FullScreen' key a value of `yes' in this domain. As with the user-specific, application-specific domain, these settings are stored in a platform-dependent fashion (see Config PerUser). Unlike settings in the user-specific, application-specific domain which are identified by the unique application identifier, settings in this domain are identified with the name `CrystalSpace.Global'.
• Application-specific settings have the next highest priority. These settings are specific to a particular application, but are shared among all users of the application. User-specific settings in higher priority domains, as well as command-line options, can override these settings. Conversely, application-specific settings can override plugin-specific settings. For instance, if the canvas plugin configuration file specifies a default resolution of 640x480, an application configuration file might override that setting by giving its own values to the `Video.ScreenWidth' and `Video.ScreenHeight' keys.

  Application-specific settings typically come from an application's configuration file. For example, the Walktest application stores its settings in the file `walktest.cfg'. As a programmer, you typically specify the application's configuration file with the following code:

  csInitializer::SetupConfigManager(object_reg, "myapp.cfg");

• Plugin-specific settings have the lowest priority. These settings define default values for options specific to plugin modules. For example, the OpenGL renderer loads configuration information from the `opengl.cfg' file, and the software renderer loads configuration from the `soft3d.cfg' file.

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.

This document was generated using texi2html 1.76.