AddProp

Introduced

v1.0

Categories

property

Description

Adds properties to objects.

Notice that UV cluster properties and vertex color properties can only be added to clusters which are always complete, see Geometry.AddCluster method.

Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference so you need to use the best workaround for your situation:

For scripting languages this command returns an ISIVTCollection which you can use to get the output arguments.

For C# you can use the XSIApplication.ExecuteCommand method to call this command. ExecuteCommand packs the output arguments into a C# System.Object containing an Array of the output arguments (see Calling Commands from C#).

Scripting Syntax

AddProp( PresetObj, [InputObjs], [Propagation], [PropertyName], [Value] );

Parameters

Parameter Type Description
PresetObj String or a preset object (see SIGetPreset) One of the Property Presets
InputObjs String List of objects.

Default Value: Currently selected objects

Propagation siPropagationType Propagation type for property

Default Value: siDefaultPropagation (node)

PropertyName String Name of property
Value XSICollection Returns the new properties in an XSICollection.

Note: For backwards compatibility, ClassName returns "Object" when you test this collection, but if you test it with XSICollection.Type, it returns "XSICollection".

Tip: Each member of the returned collection is a Property object.

Examples

1. VBScript Example

'
' This example demonstrates how to add the RenderMap property to both a sphere and 
' a cube and then shows how you can use the returned Property objects by accessing
' them as members of the returned collection.
'
' Note: In this example we are using the XSIApplication.ClassName method instead
'       of the VBScript TypeName function to provide a distinction between
'       class type and what we test with the Type property, but you can use
'       either.
'
NewScene , false
' Add a sphere to the scene
Set oSphere = CreatePrim( "Sphere", "NurbsSurface" )
' Add a sphere to the scene
Set oCube = CreatePrim( "Cube", "NurbsSurface" )
' Create rendermaps on the sphere and cube; the AddProp command returns the 
' output object as an XSICollection of 2, so you can get each RenderMap 
' as a Property object from the returned collection
AddProp "RenderMap", oSphere & "," & oCube, , , oRtnColl
' Test the type of the return value 
PrintInfo oRtnColl
' Get only the sphere's rendermap as a Property object
' Note: We could also use 'Set oRMap = oRtnColl(0)' to
'       accomplish the same thing, but this is more precise
For Each mbr In oRtnColl
        If mbr.Parent = oSphere Then
                Set oRMap = mbr
        End If
Next
' Specify a destination directory and name for the new image file
' Note: Since the new object is a real Property object, we can use
'               the object model to get its parameters
oRMap.Parameters( "imagefile" ).Value = InstallationPath( siUserPath ) _
                        & "\temp\rendermap.pic"
' Add a texture projection to the sphere and attach the rendermap to it
CreateProjection oSphere, siTxtUV, siTxtDefaultSpherical, sSupport, sProj
SetInstanceDataValue , oRMap.Parameters( "uvprop" ), sProj
' Now add an annotation property to the sphere and test it
AddProp "Annotation", oSphere, , , oNewRtnColl
PrintInfo oNewRtnColl
' This is just a utility function to separate the printing procedure
' from the rest of the example
function PrintInfo( in_coll )
        ' Print the class type (ie., Object, X3DObject, Property, etc.)
        LogMessage "========="
        LogMessage "ClassName: " & ClassName( in_coll )
        ' This prevents an error if the specified object is invalid
        if ClassName( in_coll ) <> "Nothing" then
                ' This prevents us from trying to use collection functions
                ' on a non-collection object (XSICollections returned from
                ' commands report that they have the "Object" class type:
                ' this is for backwards compatibility)
                if ( ClassName( in_coll ) = "Object" AND in_coll.Type = "XSICollection" ) _
                OR ClassName( in_coll ) = "ISIVTCollection" _
                then 
                        ' ISIVTCollections can be enumerated but they don't 
                        ' support the Type property, so we'll skip that for
                        ' ISIVTCollections
                        if ClassName( in_coll ) = "ISIVTCollection" then 
                                ' Convert the ISIVTCollection to an XSICollection (now 
                                ' we can continue with the XSICollection-specific tests)
                                Set in_coll = in_coll.item(1)
                                ' Test it again to make sure it's really an XSICollection
                                LogMessage "Type after conversion: " & in_coll.Type
                        end if
                        ' Loop through the collection and print the name, type and 
                        ' class type of each item
                        LogMessage ""
                        LogMessage "This collection contains the following ( " _
                                & in_coll.Count & " ) members ........"
                        for each member in in_coll
                                ' Note: None of this information will be printed if the 
                                ' collection is empty
                                LogMessage vbTab & "Name: " & member.Name
                                LogMessage vbTab & "Type: " & member.Type
                                LogMessage vbTab & "ClassName: " & ClassName( member )
                                LogMessage "---------"
                        next
                elseif ClassName( in_coll ) = "CollectionItem" then
                        ' Print the name, type and class type of the item
                        LogMessage vbTab & "Name: " & member.Name
                        LogMessage vbTab & "Type: " & member.Type
                        LogMessage vbTab & "ClassName: " & ClassName( member )
                end if
        end if
        LogMessage "End of collection information.................................."
end function
' Output of above script:
'INFO : "========="
'INFO : "ClassName: Object"
'INFO : ""
'INFO : "This collection contains the following ( 2 ) members ........"
'INFO : "       Name: RenderMap"
'INFO : "       Type: rendermap"
'INFO : "       ClassName: Property"
'INFO : "---------"
'INFO : "       Name: RenderMap"
'INFO : "       Type: rendermap"
'INFO : "       ClassName: Property"
'INFO : "---------"
'INFO : "End of collection information.................................."
CreateProjection "sphere", siTxtUV, siTxtDefaultSpherical, , "Texture_Projection", , siRelDefault
SetInstanceDataValue , "sphere.RenderMap.uvprop", "Texture_Projection"
AddProp "Annotation", "sphere", siDefaultPropagation
'INFO : "========="
'INFO : "ClassName: Object"
'INFO : ""
'INFO : "This collection contains the following ( 1 ) members ........"
'INFO : "       Name: Annotation"
'INFO : "       Type: customparamset"
'INFO : "       ClassName: CustomProperty"
'INFO : "---------"
'INFO : "End of collection information.................................."

2. JScript Example

/*
        This JScript example illustrates how to use the AddProp command to add an 
        annotation property to a null object. Of special interest in this example
        is how we use the returned object to extract an array of output arguments
        (since JScript does not support output arguments).
        Note: In this example we are using the XSIApplication.ClassName method 
        which is the equivalent of the VBScript TypeName function (for which
        there is no native JScript equivalent).
*/
NewScene( null , false );
// Add a null to the scene
var oSphere = GetPrim( "Null" );
// Add an annotation to the null; the AddProp command returns the output 
// object as an XSICollection of 1, so you can get the actual annotation 
// as a Property object by resetting the object pointer to the first 
// member of the returned collection
var oRtnColl = AddProp( "Annotation", oSphere, siDefaultPropagation, "Jenny" );
// Test the type of the return value 
PrintInfo( oRtnColl );
// To get the Property object, set the reference to the first member of
// the collection
//var oRMap = oRtnColl(0);
// This is just a utility function to separate the printing procedure
// from the rest of the example
function PrintInfo( in_coll )
{
        // Print the class type (ie., Object, X3DObject, Property, etc.)
        LogMessage( "=========" );
        LogMessage( "ClassName: " + ClassName( in_coll ) );
        // This prevents an error if the specified object is invalid
        if ( ClassName( in_coll ) != "Nothing" ) 
        {
                // This prevents us from trying to use collection functions
                // on a non-collection object (XSICollections returned from
                // commands report that they have the "Object" class type:
                // this is for backwards compatibility)
                if ( ( ClassName( in_coll ) == "Object" && in_coll.Type() == "XSICollection" ) || 
                        ClassName( in_coll ) == "ISIVTCollection" )
                { 
                        // ISIVTCollections can be enumerated but they don't 
                        // support the Type property, so we'll skip that for
                        // ISIVTCollections
                        if ( ClassName( in_coll ) == "ISIVTCollection" )
                        {
                                // Convert the ISIVTCollection to an XSICollection (now 
                                // we can continue with the XSICollection-specific tests)
                                in_coll = in_coll.item(1);
                                // Test it again to make sure it's really an XSICollection
                                LogMessage( "Type after conversion: " + in_coll.Type );
                        }
                        // Loop through the collection and print the name, type and 
                        // class type of each item
                        LogMessage( "" );
                        LogMessage( "This collection contains the following ( " 
                                + in_coll.Count + " ) members ........" );
                        for ( i=0; i<in_coll.count; i++ )
                        {
                                LogMessage( "\tName: " + in_coll.item(i).Name );
                                LogMessage( "\tType: " + in_coll.item(i).Type);
                                LogMessage( "\tClassName: " + ClassName( in_coll.item(i) ) );
                        } 
                }
                else 
                {
                        // Print error message 
                        LogMessage( "Object is not a collection at all." );
                }
        }
        LogMessage( "End of collection information.................................." );
}
// Output of above script:
//INFO : "========="
//INFO : "ClassName: ISIVTCollection"
//INFO : "Type after conversion: XSICollection"
//INFO : ""
//INFO : "This collection contains the following ( 1 ) members ........"
//INFO : "      Name: Jenny"
//INFO : "      Type: customparamset"
//INFO : "      ClassName: CustomProperty"
//INFO : "End of collection information.................................."

See Also

SIAddProp SceneItem.AddProperty Property XSICollection