@c -*-texinfo-*-
@node Config Domains, Specific Options, Configuration File, Options
@subsection Configuration Domains
@cindex Configuration Domains

@noindent
@emph{Written by Eric Sunshine, @email{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 @dfn{domains}) are listed first;
lowest priority sources are listed last.

@itemize @bullet
@item
Command-line options are given the highest priority.  They override settings
which appear in configuration files.  For example, the @samp{--video=} option
will override the @samp{System.Plugins.iGraphics3D} key in all configuration
files.

@item
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
(@pxref{Config PerUser}).  Often, these settings @dfn{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 @emph{unique identifier}.  Typically, this is
accomplished by placing a @samp{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 @samp{<Producer>.<ProductName>} when
constructing an application identifier.  Crystal Space example applications use
@samp{CrystalSpace} for the @var{Producer} portion of the application
identifier; for example: @samp{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.

@example
System.ApplicationID = MyCompany.MyGame
@end example

@item
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 @samp{Video.FullScreen} key a value of @samp{yes} in this
domain.  As with the user-specific, application-specific domain, these settings
are stored in a platform-dependent fashion (@pxref{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 @samp{CrystalSpace.Global}.

@item
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 @samp{Video.ScreenWidth} and
@samp{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 @file{walktest.cfg}.  As a programmer, you typically specify the
application's configuration file with the following code:

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

@item
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 @file{opengl.cfg} file.
@end itemize

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.

@anchor{Config PerUser}
@heading 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 @emph{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.

@subheading Application Unique Identifier

As noted earlier, each application uses a @emph{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
@samp{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 @samp{<Producer>.<ProductName>}.  Crystal Space example applications use
@samp{CrystalSpace} for the @var{Producer} portion of the application
identifier; for example: @samp{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.

@example
System.ApplicationID = MyCompany.MyGame
@end example

@importsss{usingcs,configuration,platform,win32.txi}
@importsss{usingcs,configuration,platform,unix.txi}
@importsss{usingcs,configuration,platform,macosx.txi}
