## 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