Implementing Control Definitions
Immediately after nodes are initialized the API calls the ControlCount method, passing an XMLTypeName. You need to return an integer value stating how many controls the document action panes needs to render for that type. Consider the itemname SmartNode, which implements ControlCount as follows:

   Public ReadOnly Property ControlCount( _
      ByVal XMLTypeName As String) As Integer _
      Implements Microsoft.Office.Interop.SmartTag. _
      ISmartDocument.ControlCount
      Get
         currentTypeName = XMLTypeName
         Return objDocument.SmartNodeControl( _
            XMLTypeName).ControlCount(XMLTypeName)
      End Get
   End Property

The call to objDocument.SmartNodeControl(XMLTypeName) returns the appropriate SmartType instance. Then you can call the ControlCount method of that instance's associated ISmartControl implementation class as shown below:

   Public Overrides Function ControlCount( _
      ByVal TypeName As String) As Integer
      Return 2
   End Function

The calls flow to the appropriate ISmartControl implementations in order shown in Table 4. The values returned here are for the itemname SmartNode, but the other SmartNodes are similar.

Table 4. Sequence of Control Calls: The Office API method calls, parameter values, and return values for the itemname SmartNode.

Property	Parameter Values	Return Value
ControlCount(ByVal XMLTypeName As String)	XMLTypeName="http://Officesamples/Customer/2004#itemname"	2
ControlID(ByVal XMLTypeName As String, ByVal ControlIndex As Integer)	XMLTypeName="http://Officesamples/Customer/2004#itemname" ControlIndex=1 XMLTypeName="http://Officesamples/Customer/2004#itemname" ControlIndex=2	301 302
ControlNameFromID(ByVal ControlID As Integer)	ControlID=301 ControlID=302	Nothing Nothing
ControlTypeFromID(ByVal ControlID As Integer, ByVal ApplicationName As String, ByVal LocaleID As Integer)	ControlID=301 ControlID=302 Note: The sample application does not use the ApplicationName or LocaleID.	C_TYPE_COMBO C_TYPE_BUTTON

Note that the ControlCount determines the number of times the API calls the methods ControlID, ControlNameFromID, and ControlTypeFromID for the given XMLType. In the sample application, the implementation returns ControlCount=2. Therefore, the API calls the properties twice for this XmlType.

The ControlID property is interesting. You must assign a unique ControlID for each execution. Here's how it's implemented:

   Public Overrides Function ControlID( _
      ByVal TypeName As String, _
      ByVal ControlIndex As Integer) As Integer
         Return Constants.ITEM_ROOT_TYPE_ID + _    
            ControlIndex
   End Function

The API increments the ControlIndex argument value by 1 each time it calls the ControlID method for a given TypeName. So if you use a constant base number for a given type—300 in this case—you can return a unique ID by adding the ControlIndex value to that. However, you should not use the same root number for any other XMLType. In this sample, documentRoot uses the value 100 and region uses the value 200 for their root identifiers, leaving space for a sufficient number of controls to add for any given XMLTypeName.

The ControlNameFromID call assigns a friendly name to each control used for a given ControlID. This is not terribly critical in the sample app; however you could use the friendly name to access the controls later. In real world applications this can help a lot while using SmartTagActions("Name") which will be discussed later.

The critical return value from ControlTypeFromID determines what type of control to render. The implementation for itemname is as follows:

   Public Overrides Function ControlTypeFromID( _
      ByVal ControlID As Integer) As _ 
      Microsoft.Office.Interop.SmartTag.C_TYPE
   
      ControlID = DocumentUtils.GetRealControlID( _
         ControlID)
      Select Case ControlID
      Case 1
         Return Microsoft.Office.Interop.SmartTag. _
            C_TYPE.C_TYPE_COMBO
      Case 2
         Return Microsoft.Office.Interop.SmartTag. _
            C_TYPE.C_TYPE_BUTTON
      End Select
   End Function

The code calls the GetRealControlID method to get the actual ControlID. This returns a ControlId Mod 100. As you can see, it returns values representing a combo box and a button.

The API initializes control parameters by calling the above properties for all XMLTypes defined. After this process is complete, it calls the OnPaneUpdateComplete. During this call, you can assume that initialization is complete and the Document actions pane is initialized.