Scripting: SetGlobal

SetGlobal

Introduced

v5.0

Description

SetGlobal and its companion command GetGlobal provide a simple means to store and retrieve values which act like "global variables". Each variable is indentified by a unique string. To change the value of a previously set variable call this command with a new value. To erase a global variable call this command with null as the value.

These variables are accessible from any script and remain active during the duration of the Softimage session.

Warning: For persistent Global values it is better to use a CustomProperty or a Custom Preferences object.

Tip 1: It is possible to store a Softimage object inside a global variable. However when storing a reference to a Softimage object, it is often safer to store the fullname string of the object rather than the object itself. This ensures that even if the scene is closed, reopened or significantly changed you can get a valid reference to the object (as long as the object isn't renamed). This is demonstrated in the examples below.

Tip 2: This command will convert any JScript Array or user-created script object into a SAFEARRAY (see Array). To maintain the data in its original form use SetGlobalObject.

Tip 3: It is unnecessary to use this functionality if the entire plug-in is implemented inside a single script, because any variable within the global scope is accessible inside all functions. (The only exception is PPGLayout logic callbacks, which cannot read the values of global variables set by non-PPGLayout callbacks.)

Tip 4: Global variables can be very useful, but usage should be kept to a minimum to avoid unexpected side-effects, "spagetti" code and code that is difficult to read, debug and maintain. Each global variable name should be well chosen to avoid potential conflict with other scripts. For example if two plug-ins both try to use a global variable named "x" then both will be prone to random or unexpected failure.

Tip 5: This feature is implemented as a self-installed JScript Plugin using the powerful "Scripting.Dictionary" object which is available to both VBScript and JScript. For more details refer to the actual implementation code (GlobalVarPlugin.js).

Scripting Syntax

SetGlobal( in_VariableName, in_Value );

Parameters

Parameter	Type	Description
in_VariableName	String	The name of the global variable
in_Value	Variant	A new value for the global variable

Examples

1. JScript Example

// Example test for GetGlobal/SetGlobal
NewScene( null, false ) ;
// null returned when Global hasn't been set
ASSERT( null == GetGlobal( "X" ) ) ;
SetGlobal( "X", 67 ) ;
ASSERT( 67 == GetGlobal( "X" ) ) ;
// You can change the value of the global
SetGlobal( "X", "foo" ) ;
ASSERT( "foo" == GetGlobal( "X" ) ) ;
// Remove the global
SetGlobal( "X", null ) ;
// Handle Softimage Object
var oGrid = ActiveSceneRoot.AddGeometry( "Grid", "MeshSurface", "mygrid" );
// You could store a Softimage object as a Global
SetGlobal( "InterestingObj", oGrid ) ;
ASSERT( oGrid.Name == GetGlobal( "InterestingObj" ).Name ) ;
// But it is better to store the string fullname
// because oGrid won't survive saving and reloading the scene,
SetGlobal( "InterestingObj", oGrid.FullName ) ;
// Simulate the user closing and reopening the scene
var strTestScene = Application.InstallationPath( siProjectPath ) + "\\Scenes\\Test.Scn" ;
SaveSceneAs( strTestScene ) ;
OpenScene( strTestScene, false ) ;
var strGrid = GetGlobal( "InterestingObj" ) ;
// Turn the string back into an object
var oGridRevived = Dictionary.GetObject( strGrid ) ;
ASSERT( oGridRevived.Name == "mygrid" ) ;
// Demonstrate that it really is a valid reference to the grid
oGridRevived.posx = 4 ;
LogMessage( "Test complete" ) ;
function ASSERT(in_val)
{
        if ( !in_val )
                throw new Error( 0, "test failed" );
}

2. VBScript Example

' Example test for GetGlobal/SetGlobal
NewScene ,false 
' null returned when Global hasn't been set
ASSERT( Null = GetGlobal( "X" ) )
SetGlobal "X", 67 
ASSERT( 67 = GetGlobal( "X" ) )
' You can change the value of the global
SetGlobal "X", "foo" 
ASSERT( "foo" = GetGlobal( "X" ) ) 
' Remove the global
SetGlobal "X", Null 
' Handle Softimage Object
set oGrid = ActiveSceneRoot.AddGeometry( "Grid", "MeshSurface", "mygrid" )
' You could store a Softimage object as a Global
SetGlobal "InterestingObj", oGrid 
ASSERT( oGrid.Name = GetGlobal( "InterestingObj" ).Name )
' But it is better to store the string fullname
' because oGrid won't survive saving and reloading the scene,
SetGlobal "InterestingObj", oGrid.FullName 
' Simulate the user closing and reopening the scene
strTestScene = Application.InstallationPath( siProjectPath ) & "\Scenes\Test.Scn"
SaveSceneAs strTestScene 
OpenScene strTestScene, false 
strGrid = GetGlobal( "InterestingObj" ) 
' Turn the string back into an object
set oGridRevived = Dictionary.GetObject( strGrid )
ASSERT( oGridRevived.Name = "mygrid" )
' Demonstrate that it really is a valid reference to the grid
oGridRevived.posx = 4 
LogMessage "Test complete"
sub ASSERT( in_test )
        if NOT in_test then
                LogMessage "Test Failed", siError 
        end if
end sub