Softimage SDK Programmer's Guide > Plug-in Development > Storing Custom (User) Data >

# Accessing Templated User Data on Components

Templated user data also uses the binary user data map, but offers more built-in functionality and interactive tools. The plug-in developer creates a user data template, which is similar to an empty parameter set, and specifies what kinds of data can be attached to the map.

The developer then associates this template with a user data map (also through scripting). The template allows a user to easily view, set, and edit the user data in the map through the user interface.

Note

Once the template has been built and associated to a particular user data map, and users have begun to associate values, you should not add or remove parameters.

For this reason, you should consider user data templates to be Read-Only.

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 Netview Tools Info 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 : "========================================================="

Tip

Notice how that the information for each cluster element (user data item) displayed is the same. That is because the user data on all subcomponents in the cluster is being inspected:

    	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.