InspectObj

Introduced

1.0

Description

Loads objects into a property editor. This allows a user to interactively view and edit the parameters of an object. You can use the siModal mode for the Mode parameter to communicate with the user (like a dialog box), as demonstrated in the first example below.

A property page can display several objects at the same time. If the objects are of different types then they will appear one after another. For example, when inspecting a Sphere, the X3DObject, Primitive and Operator are shown in this fashion. Alternatively, if the objects are of the same type then they are shown in "multi" mode. This mode is useful for changing a parameter on many objects at the same time. The examples below show both cases.

Normally when you inspect an object its nested objects will also be inspected within the same frame. You can limit which nested objects are inspected by using a list of keywords. For example, you can just display the Animation property set by specifying siAnimationKeyword in the Keywords parameter.

Scripting Syntax

    InspectObj( [InputObjs], [Keywords], [Title], [Mode], [Throw] )

Parameters

Parameter | Type | Description
InputObjs [in/out] | String | List of objects to inspect. Default Value: Current selection. Note: if the selection contains more than one object then only the first appears.
Keywords [in/out] | Keywords | Specify which property set appears for the specified object (eg., Animation, Hair, IK, Deform, etc.) Default Value: "" (clear current marking)
Title | String | Title of the property editor dialog. Note: the title you use here only appears on the property editor if you use siModal for the Mode parameter. Default Value: Generated from names of input objects.
Mode | siInspectMode | Specifies whether the dialog should be locked, recycling, focused, or modal. Default Value: siRecycle
Throw | Boolean | True to throw an error if the command is cancelled. Note: If this argument is set to false and the user cancels the command, the command returns true instead of throwing an error. Default Value: True

Return Value

Returns true if the command was canceled and the Throw argument is set to false. If the command was canceled and the Throw argument was not specified (or is set to true) the command throws an error. Otherwise, it returns false.

Examples

1. VBScript Example

    '
    ' In modal mode, a property editor has Ok and Cancel buttons.
    ' Here's how to open a modal property editor
    '

    NewScene , false

    On Error Resume Next
    InspectObj "Light",,"Inspecting Light", siModal
    ' Check if user clicked Ok
    if Err.Number = 0 then
       LogMessage "User has pressed OK in the modal property editor"
    else
       LogMessage "User has pressed CANCEL in the modal property editor"
    end if

    ' Open a property editor and lock it
    InspectObj "Camera",,, siLock
    LogMessage "User has opened a property editor and has locked it"

2. VBScript Example

    '
    '  This example demonstrates how you can inspect multiple objects on the same Property Page
    '

    NewScene , false

    SelectObj "Scene_Root"
    CreatePrim "Sphere", "MeshSurface"

    'Add a custom property set and a bend operator
    SIAddCustomParameter "sphere", "Param", siDouble, 0, 0, 1, , 5, 0, 1
    ApplyOp "Bend", "sphere", 3, siPersistentOperation

    set myPPGList = CreateObject("XSI.Collection")
    myPPGList.Add "sphere.CustomPSet"
    myPPGList.Add "sphere.polymsh.bendop"

    'The property page will show both the custom property set and
    'the bend operation.
    InspectObj myPPGList

3. VBScript Example

    '
    '  The following uses InspectObj to inspect several properties
    '  in a multi-edit fashion
    '

    NewScene , false

    CreatePrim "Sphere", "MeshSurface"
    CreatePrim "Cylinder", "MeshSurface"
    SelectObj "cylinder.kine.global,sphere.kine.global"

    InspectObj

    LogMessage "The global kinestate of both the sphere and the cylinder"
    LogMessage "are inspected together in a bulk-edit fashion"

4. VBScript Example

    ' Set up a sphere
    NewScene ,False
    set oSphere = CreatePrim( "Sphere", "MeshSurface" )

    ' Open a general property editor
    InspectObj , siGeneralKeyword

    ' Set up a deform on the sphere
    ApplyOp "Bulge", oSphere, 3, siPersistentOperation

    ' Open the Deform property editor for the sphere
    InspectObj , siDeformKeyword

    ' Add some animation
    SaveKey oSphere.active
    SetValue "PlayControl.Key", 65
    SetValue "PlayControl.Current", 65
    Translate , 3.9582518712148, 3.40954109797705, -0.340954109797705, siRelative, siView, siObj, siXYZ
    SaveKey oSphere.active

    ' Open the Animation property editor for the sphere
    InspectObj , siAnimationKeyword

5. VBScript Example

    '
    '  Another example demonstrating inspecting objects in multi-edit mode.
    '

    NewScene , false

    SelectObj "Scene_Root"
    set oSphere1 = CreatePrim( "Sphere", "MeshSurface", "FirstSphere")
    set oSphere2 = CreatePrim( "Sphere", "MeshSurface", "SecondSphere")

    set myPPGList = CreateObject("XSI.Collection")
    myPPGList.Add oSphere1.Primitives(1)
    myPPGList.Add oSphere2.Primitives(1)

    'The property page will show just a single Radius control
    'that will control both spheres
    InspectObj myPPGList, "Primitive"

6. JScript Example

    /*
       This example shows how to create a temporary instance of the Self-Installed
       Custom Property called "CustomColor".
    */

    var oColor = XSIFactory.CreateObject( "CustomColor" )
    bCancelled = InspectObj( oColor,null,"Pick your favorite color",siModal,false ) ;

    if ( !bCancelled )
    {
       LogMessage( "You picked " + oColor.Color_R.Value + "," + oColor.Color_G.Value + "," + oColor.Color_B.Value ) ;
    }

7. JScript Example

    /*
       This example demonstrates the use of the Throw argument.
       When you run this script, make sure you close the dialog using
       the X (close) button on the top right or the Cancel button in
       the main body of the dialog.
    */

    // Set up a quick dialog in a property page
    NewScene( null, false );
    var pset = SetUpPSet();

    // Canceling here returns 'true'
    var rtn1 = InspectObj( pset, "", "Throw = FALSE", siModal, false );
    LogMessage( "Value returned: " + rtn1 );

    // Canceling here throws an error.
    try
    {
       var rtn2 = InspectObj( pset, "", "Throw = TRUE", siModal );

       // This line is never executed if the user presses cancel
       LogMessage( "Value returned: " + rtn2 );
    }
    catch(e)
    {
       LogMessage( "User cancelled" );
    }

    // This is a convenience function that sets up the property page apart
    // from the main demo
    function SetUpPSet( )
    {
       // Create the underlying pset
       var prop = XSIFactory.CreateObject("CustomProperty");
       prop.Name = "Jetsam" ;
       prop.AddParameter3( "SelectOne", siFloat, 0 );

       // Set up its appearance
       var pout = prop.PPGLayout;
       var avals = new Array(
           "One", 1,
           "Two", 2,
           "Three", 3,
           "Four", 4,
           "Five", 5
       );
       pout.AddEnumControl( "SelectOne", avals, "", siControlCombo );

       // Return the property set
       return prop;
    }

See Also

PPG | PPGLayout

Autodesk Softimage v7.5