Accessing Templated User Data on Components

VBScript Example: Creating a user data template

1. The first part of this procedure consists of creating the template, which is the same as creating a custom parameter set:

   ' Create a grid 
   Set oRoot = ActiveSceneRoot
   Set oGrid = oRoot.AddGeometry( "Grid", "MeshSurface" )
   
   ' Create a custom parameter set
   aCls = Array( 27,28,35,36 )
   Set oCluster = oGrid.ActivePrimitive.Geometry.AddCluster( siPolygonCluster,, _
   						aCls )
   Set oParamSet = oCluster.AddProperty( "Custom_parameter_list")
   
   oParamSet.AddParameter "Juiciness_Factor", siFloat,,,,,, 25, 0, 50
   oParamSet.AddParameter "Special_Instructions", siString
   oParamSet.AddParameter "Toggle_Effect", siBool,,,,,, True
   

   Note

   You can create the template either through scripting or through the user interface. For instructions on creating custom parameter sets through the user interface, see the Animation guide.

   The result of this script is a template that looks like this:

   

2. The next step is to create a user data map through scripting and associate the new template to it.

   ' Attach a user data map to a cluster on the grid
   Set oUDMap = oCluster.AddProperty( "UserDataMap" )
   
   ' Associate the template to the new user data map
   Set oUDMap.Template = oParamSet
   

3. Once this association is made, you can provide user interaction through a parameter dialog box.

   ' Change some values on selected clusters
   Set oSubComp = oGrid.ActivePrimitive.Geometry.CreateSubComponent( _
   		siPolygonCluster, aCls )
   SIInspectUserData oUDMap, oSubComp
   

   The following message is logged to the History Log of the Script Editor:

   'SIInspectUserData "grid1.polymsh.cls.Polygon.User_Data_Map", "grid1.poly[27,28,35,36]"
   

   Note

   SIInspectUserData is a scripting command, so if you are planning to use it in a compiled plug-in, you will need to use the XSIApplication.ExecuteScriptCommand method. At this time, there is no equivalent functionality in the object model.

4. You can see any changes made to these values have been updated by running the OMView tool (see NetviewToolsInfo OM) while the user data map is selected.

   Alternatively, you can access information about the values stored on the user data map by using the UserDataMap.ItemValue property. For more information, see VBScript Example: Getting user data on specific elements.

VBScript Example: Getting user data on specific elements

1. Follow the steps under VBScript Example: Creating a user data template to create and modify templated user data.

   Call printInfo( oUDMap )
   
   function printInfo( in_oUDMap )
   

2. Use the UserDataMap.Template property to get the template.

   Set oTemplate = in_oUDMap.Template
   

3. Use the UserDataMap.Item property to get the user data on each individual cluster element as a UserDataItem object.

   Tip

   You should test each item to see whether it contains data, since the whole user data map may be associated to a cluster with a lot of unused elements.

   	For iCounter = 0 to in_oUDMap.Count - 1
   		LogMessage "========================================================="
   		LogMessage "Information for Point #" & (iCounter + 1)
   		LogMessage "---------------------------------------------------------"
   		If (Not oUDMap.IsEmpty(iCounter)) Then
   			Set oUDItem = in_oUDMap.Item(iCounter)
   			oTemplate.BinaryData = oUDItem.Value
   

   Note

   Using the UserDataItem object is the equivalent to using the UserDataMap.ItemValue property. For an example using the UserDataMap.ItemValue property, see VBScript Example: Setting user data on specific elements with UserDataMap.ItemValue.

4. Iterate over each parameter in the template to get its value (each piece of user data can be accessed as a user data map template parameter).

   	
   			For Each oParam in oTemplate.Parameters
   				If oParam.Value = "" Then
   					LogMessage oParam.ScriptName & ": (no data)"
   				Else
   					LogMessage oParam.ScriptName & ": " & oParam.Value
   				End If
   			Next
   		End If
   	Next
   
   	LogMessage "========================================================="
   end function
   

   The following message is logged to the History Log of the Script Editor:

   'INFO : "========================================================="
   'INFO : "Information for Point #1"
   'INFO : "---------------------------------------------------------"
   'INFO : "Juiciness_Factor: 25"
   'INFO : "Special_Instructions: (no data)"
   'INFO : "Toggle_Effect: True"
   'INFO : "========================================================="
   'INFO : "Information for Point #2"
   'INFO : "---------------------------------------------------------"
   'INFO : "Juiciness_Factor: 25"
   'INFO : "Special_Instructions: (no data)"
   'INFO : "Toggle_Effect: True"
   'INFO : "========================================================="
   'INFO : "Information for Point #3"
   'INFO : "---------------------------------------------------------"
   'INFO : "Juiciness_Factor: 25"
   'INFO : "Special_Instructions: (no data)"
   'INFO : "Toggle_Effect: True"
   'INFO : "========================================================="
   'INFO : "Information for Point #4"
   'INFO : "---------------------------------------------------------"
   'INFO : "Juiciness_Factor: 25"
   'INFO : "Special_Instructions: (no data)"
   'INFO : "Toggle_Effect: True"
   'INFO : "========================================================="
   

	Set oSubComp = oGrid.ActivePrimitive.Geometry.CreateSubComponent( _
			siPolygonCluster, aCls )
	SIInspectUserData oUDMap, oSubComp

If you want to change the data on individual elements, you can either use the UserDataMap.ItemValue property for each cluster element (see VBScript Example: Setting user data on specific elements with UserDataMap.ItemValue) or use the SIInspectUserData command on a SubComponent that is derived from a single component of the cluster:

	Set oSubComp = oGrid.ActivePrimitive.Geometry.CreateSubComponent( _
			siPolygonCluster, array(27) )
	SIInspectUserData oUDMap, oSubComp

VBScript Example: Setting user data on specific elements with UserDataMap.ItemValue

1. Follow the steps under VBScript Example: Creating a user data template to create and modify templated user data.

   ' Change the values on some individual points
   Call setValues( oUDMap, 0, 12, "Generic", False )
   Call setValues( oUDMap, 1, 7, "Low", False )
   Call setValues( oUDMap, 2, 23, "Severus", True )
   

2. You can access each parameter of the templated data through the Template property on the UserDataMap object:

   sub setValues( in_objUDM, in_intID, in_strPar1, in_strPar2, in_strPar3 )
   	' Assign the specified values to the individual parameters of the template
   	in_objUDM.Template.Parameters("Juiciness_Factor").Value = in_strPar1
   	in_objUDM.Template.Parameters("Special_Instructions").Value = in_strPar2
   	in_objUDM.Template.Parameters("Toggle_Effect").Value = in_strPar3
   

3. Even though you have updated the templated data attached to the user data map, you still need to save those values back to the user data map in order for them to take effect. To save it to a specific point, use the matching UserDataMap.ItemValue property:

   ' Assign the template values back to the user data map
   in_objUDM.ItemValue(in_intID) = in_objUDM.Template.BinaryData
   end sub
   

   Note

   Using the UserDataMap.ItemValue property is the equivalent to using the UserDataItem object. For an example using the UserDataItem object, see VBScript Example: Getting user data on specific elements.