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 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 : "========================================================="
    
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.

Creative Commons License Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License