InspectObj
 
 
 

InspectObj

Introduced

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

oReturn = InspectObj( [InputObjs], [Keywords], [Title], [Mode], [Throw] );

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.

Parameters

Parameter Type Description
InputObjs 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 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

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