Difference between revisions of "How preferences work"

From Second Life Wiki
Jump to navigation Jump to search
 
(Major expansion of article coverage)
Line 1: Line 1:
Adding a user preference:
This document contains information about how user preferences are stored and manipulated in the Second Life Viewer Client.


To access a user preference in code, a global called gSavedSettings is used to store stuff in settings.xml. Adding a new setting to settings.xml requires that you add it to your personal settings file, as well as settings_default.xml. Additonally, you need to declare it in llcontroldef.cpp for it to be accessible.
== The gSavedSettings Control Group ==


gSavedSettings is of type llcontrolgroup inside of llcontrol.h, which may be nonobvious.
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 ==
 
All preferences must be declared in "indra/newview/llcontroldef.cpp" to be used. The declaration informs the client of details about the preference:
* its data type (e.g. color, string, float);
* its name (e.g. "EffectColor");
* its initial (default) value;
* its documentation string, which is displayed in the "Debug Settings" floater (in the Client menu);
* (optional) its persistence, i.e. whether it will be 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);
 
The full list of data types, their declaration function names, and data type descriptions follows. Note that for data types which start with "LL" (e.g. LLString), the declare function name does not contain the leading "LL" (thus it becomes "declareString", not "declare'''LL'''String")
 
{|border="1" cellpadding="10px"
!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:
 
{|border="1" cellpadding="10px"
!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.
|}

Revision as of 23:27, 9 March 2007

This document contains information about how user preferences are stored and manipulated in the Second Life Viewer Client.

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

All preferences must be declared in "indra/newview/llcontroldef.cpp" to be used. The declaration informs the client of details about the preference:

  • its data type (e.g. color, string, float);
  • its name (e.g. "EffectColor");
  • its initial (default) value;
  • its documentation string, which is displayed in the "Debug Settings" floater (in the Client menu);
  • (optional) its persistence, i.e. whether it will be 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);

The full list of data types, their declaration function names, and data type descriptions follows. Note that for data types which start with "LL" (e.g. LLString), the declare function name does not contain the leading "LL" (thus it becomes "declareString", not "declareLLString")

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.
Retrieved from "https://wiki.secondlife.com/w/index.php?title=How_preferences_work&oldid=15244"