<     > 

AddProp

Introduced

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

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

Autodesk Softimage v7.5     <     >