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