v1.0

Returns the value of a parameter at a specific frame. This is a very powerful command because it can apply to any parameter, and it can convert a return value to an object in some cases. It also isn't necessarily tied to a parameter, as in the case of using it to return a collection of selected objects.

The example below demonstrates how versatile this command is. It returns whatever value the parameter contains, no matter what type of value it is. If the parameter or entity is attached to an object, then the object is returned, rather than a simple data value (like a string with the name of the object). For example, the following statement returns an XSICollection of selected items:

Set objSel = GetValue( "SelectionList" )

Note: If this command returns an object (instead of a simple data value) and you are using VBScript, you must use the 'Set' keyword in order to get the object. If you omit 'Set', the string name of the object(s) is returned instead.

On the other hand, if you try to assign a simple data value to an object, this command generates an 'Object required' error message. For example, if you tried to assign the returned posx value as an object as in this case:

Set dblX = GetValue( "circle.kine.local.pos.posx" )

You can usually test for the return value by using the TypeName() function for VBScript (which reports back object type as well as simple data type). For JScript, you can use the ClassName() method, which reports on the object type or the typeof operator, which reports only on the simple data type.

The counterpart to this command is the SetValue command, which allows you to set parameter values.

The Object Model provides alternatives to GetValue and SetValue. For example, parameter values can be retrieved and modified using Parameter.Value as demonstrated in the second example below. In addition, objects can be retrieved using Dictionary.GetObject.

oVariant = GetValue( Target, [Time] );

Variant

Parameter	Type	Description
Target	String	Parameter value to retrieve.
Time	Number	Frame at which to get the value. Default Value: Current frame.

1. VBScript Example

'

'    This example just demonstrates some of the different values 

'    you can find using this command. 

'       NB: If you want to use the GetValue command to return

'           an object, you need to use the 'Set' keyword for VBScript

'

rtn = GetValue("Camera.aspect")

LogMessage TypeName(rtn)				' returns Double

rtn = GetValue("Camera.kine.posz", 25)

LogMessage TypeName(rtn)				' returns Boolean

rtn = GetValue("light.Name")

LogMessage TypeName(rtn)				' returns String

' GetValue() on an object just returns the object:

set rtn = GetValue("Layers.Layer_Default")

LogMessage TypeName(rtn)				' returns Layer

' You can also convert the selection list to the selection object

set rtn = GetValue("SelectionList")

LogMessage TypeName(rtn)				' returns Object (= collection)

LogMessage rtn.Type					' returns XSICollection

LogMessage TypeName(rtn(0))				' returns X3DObject

2. JScript Example

/*

This example demonstrates how you can get and set parameter values

using one of the following:

(1) GetValue or SetValue scripting commands

(2) the Parameter object (long version)

(3) a shortcut to the Parameter object

*/

NewScene( null, false);

// First start by getting an object pointer to the sphere, which we will

// use with the object model versions

ActiveSceneRoot.AddGeometry( "sphere", "meshsurface" );

var oSphere = ActiveSceneRoot.FindChild( "Sphere" );

// (1) Change the sphere's posx value using commands:

dblX = GetValue( "sphere.kine.local.pos.posx" );

dblX = dblX - 1.25;

SetValue( "sphere.kine.local.pos.posx", dblX );

// (2) Restore the value but this time use the OM (long way)

dblX = oSphere.Kinematics.Local.Parameters( "posx" ).Value;

dblX = dblX + 1.25;

oSphere.Kinematics.Local.Parameters( "posx" ).Value = dblX;

// (3) Change the value back again with the OM shortcut

dblX = oSphere.posx.Value;

dblX = dblX + 1.25;

oSphere.posx.Value = dblX;

SetValue Parameter Dictionary.GetObject ToggleValue