|[ < ]||[ > ]||[ << ]||[ Up ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
Written by Eric Sunshine, firstname.lastname@example.org.
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.
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
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:
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.
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.
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
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.
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.
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:
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.
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.