# Prefsfile module - background information

## The cascade

The cascade.

### Concept

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.

#### Four-level cascade

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.

#### Two-level cascade

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 system fixed preferences

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.

### The user preferences

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 default preferences

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.

### Built-in compile- or run-time defaults

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.

## References

1. System Administrator's Handbook (external documentation).