SetGlobal

Introduced

5.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

See Also

GetGlobal | SetGlobalObject | CustomProperty | XSIFactory.CreateObject

Autodesk Softimage v7.5