## AddProp

### Introduced

v1.0

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