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


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

Returns

the VRTree node associated with the root of the settings hierarchy


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


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

No Results.

Getting StartedArchitectureBest PracticesHow ToAdvanced TopicsChangelogvrtree_cppCoreForeign Function InterfaceMetanodesMigrationsObserversPropertiesSettingsTreeUtilitiesAPI DefinitionsVR ExchangePluginsLua API