How preferences work

Category:Viewer Architecture
This articles describes how the Second Life Viewer stores and manipulates preferences.
For a description of all the preferences settings, see Debug Settings.
== The gSavedSettings control group ==
The values for user preferences are stored in gSavedSettings, a global variable of the class LLControlGroup (see "indra/llxml/llcontrol.cpp" for the definition of that class). At the end of the session (i.e. when the viewer client is quit), persistent settings are saved to "settings.xml". They will be loaded from that file at the beginning of the next session.
== Declaring a New Preference ==
As of Viewer relese 1.20 the settings system uses an XML file, app_settings/settings.xml, to control settings values.
This file provides the following information for each preference setting:
* Data type
* Name 
* Default value
* Documentation string, displayed in the "Debug Settings" floater (in the advanced menu);
* (optional) persistence, that is, whether it is saved between sessions.
The following example (taken from "indra/newview/llcontroldef.cpp") declares a preference which stores a 4-channel (RGBA) color, called "EffectColor", with a default value of totally-opaque white (1, 1, 1, 1), and a documentation string, "Particle effects color":
 gSavedSettings.declareColor4("EffectColor", LLColor4(1.f, 1.f, 1.f, 1.f), "Particle effects color");
This next example shows how you can specify that the preference should NOT persist between sessions, by giving NO_PERSIST as a fourth argument to the declaration:
 gSavedSettings.declareBOOL("ShowTools", FALSE, "", NO_PERSIST);
=== Data types ===
The following table describes the data types valid for preferences. For data types that start with "LL", the declare function name does not contain the leading "LL." For example data type LLString the declare function is "declareString."
Data Type 	Declare Function	Description
U32 	declareU32 	Unsigned 32-bit Integer
S32 	declareS32 	Signed 32-bit Integer
F32 	declareF32 	32-bit Float
BOOL 	declareBOOL 	Boolean (True/False)
LLString 	declareString 	Character String (Text)
LLVector3 	declareVec3 	3D Vector
LLVector3d	declareVec3d 	3D Vector (double data size)
LLRect 	declareRect 	Rectangle (left, bottom, width, height)
LLColor4U 	declareColor4U 	Unsigned 4-Channel Color (RGBA)
LLColor4 	declareColor4 	4-Channel Color (RGBA)
LLColor3 	declareColor3 	3-Channel Color (RGB)
== Accessing preference data ==
The LLControlGroup class (of which gSavedSettings is an instance) defines "get" and "set" functions for each of the data types. The functions follow this format, where "DataType" is replaced with the proper data type, e.g. BOOL, F32, LLColor4. As with the declare functions, the get and set function names to not contain the leading "LL" for data types like LLString and LLColor4.
 LLControlGroup::getDataType( LLString name );
 LLControlGroup::setDataType( LLString name, DataType new_value );
A contrived example of retrieving and then setting an LLColor4-typed preference:
 LLColor4 my_color;
 my_color = gSavedSettings.getColor4( "EffectColor" );
 gSavedSettings.setColor4( "EffectColor", my_color );
There are three additional "get" functions for certain special cases:
Function Name	Return Type	Description
getWString 	LLWString 	Wide-Data Strings (multiple bytes per char)
getText 	LLString 	Special handler for strings from a file?
getColor 	LLColor4 	Handles both LLColor4 and LLColor4u types.