Copyright © 1995-2012 Opera Software ASA. All rights reserved.
This file is part of the Opera web browser. It may not be distributed
under any circumstances.
$Id$
The cascade.
A central concept in the design of the Prefsfile module is the cascade of preferences, which is named so after the similar concept in CSS. Basically this means that there are several layers of preferences available, that can be set by different people.
The cascade is implemented in the PrefsFile class, which is the main interface used by most platforms. Some platforms may implement their own code in place of PrefsFile, but that is beyond the scope of this documentation.
The cascade used in PrefsFile involves three levels of files
and the compiled-in defaults.
This four-level cascade is indicated with the black arrows in the diagram.
When requesting the value of a setting, these three file levels will be checked
in order, returning the value from the first file found.
It is possible to disable the cascade by disabling the
FEATURE_PREFS_CASCADE setting.
In this case, only the user settings file and the built-in settings will be
used, as indicated by the blue arrows in the diagram.
This mode of operation is typically used on system where there is no concept
of system administrator, or where such support is not needed, mainly in
embedded deliveries.
The global fixed files contains settings that the user running Opera is not allowed to change, and is aimed for system administrators that want to enforce certain settings on the user, to disable certain features or enable the use of others. There can be any number of global fixed files in the cascade, the number is specified in the call to the constructor for the PrefsFile class. The files are searched in the priority order given when setting up the PrefsFile object, with 0 being the highest priority. These files should normally be placed in a directory where normal users do not have write access.
If you try to write to a preference that is defined in one of the global fixed files,
nothing will be changed and an error code will be returned to the caller.
There is an API called AllowedToChangeL() which checks if the
setting is not set in the global fixed file.
This is the regular preferences file (for the main configuration usually
called opera.ini or something similar), which the user has
access to and can edit.
On regular desktop systems, the user will normally have access to edit this
file manually.
Changes done using the regular write methods will end up in this file,
unless they are blocked by the
global fixed preferences as described above.
There can be only one user preference file.
The global preferences files contains fallback settings, and can be set by the installer or by the system administrator to provide defaults that are tailored for that particular installation. The installers usually use this to set paths to files that can move depending on the installation, and the system administrator can use this to set a default home page to replace the regular Opera portal page.
There can be any number of global files in the cascade, the number is specified in the call to the constructor for the PrefsFile class. The files are searched in the priority order given when setting up the PrefsFile object, with 0 being the highest priority. This can be used, for instance, to allow for several levels of fallback, one created by the installer, one depending on the user's locale, and so on.
If you enable the corresponding tweak setting, it is also possible to write to these files from inside Opera. This should be handled with care, but can be useful when you need to make a distinction between settings changed by the user and automatic settings, for instance settings downloaded from a server.
The lowest level of the preference cascade is defined at compile or run time by using the default value argument to the reader methods. When the settings requested is not available in any of the files defined by the cascade, the default value will be returned instead.