Settings

Functions for accessing settings.

Functions

int VRAddCallbackSettingChanged(	const char *	path,
	SettingChangedFunc	func,
	void *	userData
	)

Registers a function to be called when a setting value changes.

Parameters

path	the path from the root of the settings hierarchy
func	the function to be called
userData	an arbitrary value to be passed to the callback function

Returns: 0 on success, 1 on failure

int VRAddSettingToScene(

const char *

path

)

Adds a scene override of a setting (if it doesn't already exist) and copies the value from the user setting to the override.

Parameters

path	the path from the root of the settings hierarchy

Returns: 0 if an override was added or already present, or 1 on failure

int VRCreateSettingArrayDouble(	const char *	path,
	size_t	count,
	const double *	defaultValues
	)

Creates a double array setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
count	the number of elements in the array (may be 2, 3, 4, 9 or 16)
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingArrayFloat(	const char *	path,
	size_t	count,
	const float *	defaultValues
	)

Creates a float array setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
count	the number of elements in the array (may be 2, 3, 4, 9 or 16)
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingArrayInt(	const char *	path,
	size_t	count,
	const int *	defaultValues
	)

Creates an integer array setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
count	the number of elements in the array (may be 2, 3 or 4)
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingBool(	const char *	path,
	char	defaultValue
	)

Creates a boolean setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingDouble(	const char *	path,
	double	defaultValue
	)

Creates a double setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingFloat(	const char *	path,
	float	defaultValue
	)

Creates a float setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingInt(	const char *	path,
	int	defaultValue
	)

Creates an integer setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingLink(

const char *

path

)

Creates a link setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

int VRCreateSettingString(	const char *	path,
	const char *	defaultValue
	)

Creates a string setting if it doesn't already exist.

Parameters

path	the path from the root of the settings hierarchy
defaultValue	the value to set if the setting didn't already exist

Returns: 0 if the setting was created or already existed, or 1 on failure

HNode VRGetRootSettingNode(

)

Gets the VRTree node associated with the root of the settings hierarchy.

Returns: the VRTree node associated with the root of the settings hierarchy

HNode VRGetSceneRootSettingNode(

)

Gets the VRTree node associated with the root of the scene overrides, if present.

Returns: the VRTree node associated with the root of the scene overrides, or 0 if no overrides are present

HNode VRGetSettingNode(

const char *

path

)

Gets the VRTree node associated with a setting. If the setting has a scene override, the override node is returned; otherwise, the user setting node is returned.

Parameters

path	the path from the root of the settings hierarchy

Returns: the VRTree node currently associated with the setting

size_t VRGetSettingSize(

const char *

path

)

Returns the number of bytes required to store a setting's value. For string settings, this includes the terminating null character.

Parameters

path	the path from the root of the settings hierarchy

Returns: the size of the value in bytes, or 0 on failure

size_t VRReadSettingArrayDouble(	const char *	path,
	double *	values,
	size_t	count
	)

Reads a double array setting.

Parameters

path	the path from the root of the settings hierarchy
values	pointer to a buffer to receive the data
count	the size of the buffer (number of double elements)

Returns: the number of values written to the buffer

size_t VRReadSettingArrayFloat(	const char *	path,
	float *	values,
	size_t	count
	)

Reads a float array setting.

Parameters

path	the path from the root of the settings hierarchy
values	pointer to a buffer to receive the data
count	the size of the buffer (number of float elements)

Returns: the number of values written to the buffer

size_t VRReadSettingArrayInt(	const char *	path,
	int *	values,
	size_t	count
	)

Reads an int array setting.

Parameters

path	the path from the root of the settings hierarchy
values	pointer to a buffer to receive the data
count	the size of the buffer (number of int elements)

Returns: the number of values written to the buffer

char VRReadSettingBool(

const char *

path

)

Reads a boolean setting.

Parameters

path	the path from the root of the settings hierarchy

Returns: the setting value, or 0 on failure

double VRReadSettingDouble(

const char *

path

)

Reads a double setting.

Parameters

path	the path from the root of the settings hierarchy

Returns: the setting value, or 0 on failure

float VRReadSettingFloat(

const char *

path

)

Reads a float setting.

Parameters

path	the path from the root of the settings hierarchy

Returns: the setting value, or 0 on failure

int VRReadSettingInt(

const char *

path

)

Reads an int setting.

Parameters

path	the path from the root of the settings hierarchy

Returns: the setting value, or 0 on failure

HNode VRReadSettingLink(

const char *

path

)

Reads a link setting.

Parameters

path	the path from the root of the settings hierarchy

Returns: the setting value, or 0 on failure

size_t VRReadSettingString(	const char *	path,
	char *	buffer,
	size_t	bufferSize
	)

Reads a string setting.

Parameters

path	the path from the root of the settings hierarchy
buffer	pointer to buffer to receive the string data
bufferSize	the size of the buffer

Returns: the number of bytes written to the buffer

Note

if buffer is null, the function returns the required size of the buffer

int VRRemoveCallbackSettingChanged(	const char *	path,
	SettingChangedFunc	func
	)

Removes a callback that was added with VRAddCallbackSettingChanged()

Parameters

path	the path from the root of the settings hierarchy
func	the callback function

Returns: 0 on success, 1 on failure

int VRRemoveSettingFromScene(

const char *

path

)

Removes a scene override of a setting.

Parameters

path	the path from the root of the settings hierarchy

Returns: 0 on success, 1 on failure

int VRSetSettingCaption(	const char *	path,
	const char *	caption
	)

Assigns a custom caption to a setting, allowing the text displayed to in user interface to be different from the setting name.

Parameters

path	the path from the root of the settings hierarchy
caption	the caption to be displayed in the user interface

Returns: 0 on success, 1 on failure

int VRSetSettingFilter(	const char *	path,
	const char *	filter
	)

Assigns a filter to a setting. The meaning of the filter depends on the setting type:

Setting type	Filter meaning
string with type "file", "filesave" or "stream"	List of allowable file extensions specified as pairs of strings separated by \|, e.g. "Text files\|.txt\|HTML files\|.htm;*.html"
link	List of allowable node types separated by commas, e.g. "StdMaterial,Texture"

Parameters

path	the path from the root of the settings hierarchy
type	the filter to assign

int VRSetSettingRange(	const char *	path,
	double	minValue,
	double	maxValue
	)

Assigns a range to a numeric setting.

Parameters

path	the path from the root of the settings hierarchy
minValue	the minimum allowable value
maxValue	the maximum allowable value

int VRSetSettingStep(	const char *	path,
	double	step
	)

Assigns a step size to a numeric setting.

Parameters

path	the path from the root of the settings hierarchy
step	the step size

int VRSetSettingType(	const char *	path,
	const char *	type
	)

Assigns a type to a setting, which determines how the setting is presented in the user interface. The types that can be assigned depend on the data type of the setting:

Data type	Valid type names
string	image, file, filesave, stream, dir, font, password, singlelinetext
int/float/double	slider, logslider, log2slider, collisiongroupmask
float array (3 or 4 elements)	colour
int/float/double array (4 elements)	rect, sphere
int/float/double array (16 elements)	matrix, 2dmatrix

Parameters

path	the path from the root of the settings hierarchy
type	the type name

int VRWriteSettingArrayDouble(	const char *	path,
	const double *	values,
	size_t	count
	)

Sets the value of a double array setting.

Parameters

path	the path from the root of the settings hierarchy
values	the values to set
count	the number of values

Returns: 0 on success, 1 on failure

int VRWriteSettingArrayFloat(	const char *	path,
	const float *	values,
	size_t	count
	)

Sets the value of a float array setting.

Parameters

path	the path from the root of the settings hierarchy
values	the values to set
count	the number of values

Returns: 0 on success, 1 on failure

int VRWriteSettingArrayInt(	const char *	path,
	const int *	values,
	size_t	count
	)

Sets the value of an int array setting.

Parameters

path	the path from the root of the settings hierarchy
values	the values to set
count	the number of values

Returns: 0 on success, 1 on failure

int VRWriteSettingBool(	const char *	path,
	char	value
	)

Sets the value of a boolean setting.

Parameters

path	the path from the root of the settings hierarchy
value	the value to set

Returns: 0 on success, 1 on failure

int VRWriteSettingDouble(	const char *	path,
	double	value
	)

Sets the value of a double setting.

Parameters

path	the path from the root of the settings hierarchy
value	the value to set

Returns: 0 on success, 1 on failure

int VRWriteSettingFloat(	const char *	path,
	float	value
	)

Sets the value of a float setting.

Parameters

path	the path from the root of the settings hierarchy
value	the value to set

Returns: 0 on success, 1 on failure

int VRWriteSettingInt(	const char *	path,
	int	value
	)

Sets the value of an int setting.

Parameters

path	the path from the root of the settings hierarchy
value	the value to set

Returns: 0 on success, 1 on failure

int VRWriteSettingLink(	const char *	path,
	HNode	value
	)

Sets the value of a link setting.

Parameters

path	the path from the root of the settings hierarchy
value	the value to set

Returns: 0 on success, 1 on failure

int VRWriteSettingString(	const char *	path,
	const char *	value
	)

Sets the value of a string setting.

Parameters

path	the path from the root of the settings hierarchy
the	value to set

Returns: 0 on success, 1 on failure