Maintaining the State of Smart Document Controls [Office 2003 SDK Documentation]

Text box, check box, radio button, combo box, or list box controls don't automatically maintain state when you use them in a smart document. Every time the task pane redraws a control, the state reverts to the value in the associated populate method. As a result, you should understand the various ways to maintain the state of these controls when planning and developing your smart documents.

Following are several possible ways to maintain the state of smart document controls:

Using information from the document

If the state of a control can be determined from information within the document, you can use the document to determine what the state of the control should be. For example, if you use a check box to turn a document property or view mode on or off, you can use that property to determine the state of the check box each time the host application redraws the task pane that contains the control. You could also use the value of an element or attribute, or the presence or absence of an element or attribute, to determine the value of controls.

Using global variables

You can also maintain state using global variables. You create a global variable to store the value or state of a control every time the value or state changes. Then, in the populate method for the control, you set the value or state of the control equal to the value of the global variable.

However, global variables only work if you have only one document open that uses a specific XML expansion pack. If you have multiple documents open, and more than one of those documents uses the same XML expansion pack, your global variables are tied to the ISmartDocument interface, of which there is only one instance for the XML expansion pack, not for each individual instance of a smart document.

Using separate hives of state variables

Another way to maintain the state of smart document controls is to create hives of variables using the Dictionary object of the Microsoft Scripting Runtime.

Important  To use the Microsoft Scripting Runtime, you need to add a reference to it in your project. In addition, if you are creating a managed smart document, you would need to include the Microsoft® Visual Studio® .NET interop assembly for the Microsoft Scripting Runtime with the XML expansion pack manifest file and include a reference to the interop assembly within the XML expansion pack manifest file.

The following example shows how the Scripting Runtime might be used.

Note  This is not actual code and is used only as an example.

Dim objDictionary as Scripting.Dictionary

Sub AddHive (Doc as Object)
    Dim objHive as new Scripting.Dictionary
    objDictionary.Add Doc, objHive
End Sub

Sub GetHive (doc as Object)
    Dim objHive as Scriping.Dictionary
    Set objHive = objDictionary.Item doc
End Sub

Sub PutValueToHive (doc as Object, key as string, value as object)
    GetHive (doc).Item(key) = value
End Sub
    
Function GetValueFromHive (doc as Object, key as string, value as object)
    GetValueFromHive = GetHive (doc).Item(key)
End Function

Sub SmartDocInitialize
    AddHive(Doc)
End Sub

Sub PopulateTextBox(Target as Object, controlID as Integer)
    'Find the instance of the document
    Dim objDoc as Word.Document
    Set objDoc = Target.Document

    'Retrieve the value of MyTextBox
    Dim objVal as Object
    Set objVal = GetValueFromHive Doc, "MyTextBox"

    Dim strVal as String
    strVal = objVal

    PopulateTextBox = strVal
End Sub

For more information about using the Microsoft Scripting Runtime, see the Scripting Runtime Library on MSDN®, the Microsoft Developer Network.

Using custom document properties

The Microsoft® Office Visual Basic for Applications® (VBA) object model allows for creating custom document properties that are stored within the document itself. You can use the DocumentProperties object of the Office VBA object model to create custom properties.

Note  In Microsoft Office Word 2003, you can also use document variables by using the Variables property of the Document object. For more information, see VBA Help in Word.

To do this, you would create a custom property in the SmartDocInitialize method. Then in the appropriate populate method for the control, you would set the value of the control to the value in the custom property, and in the appropriate change method for the control, you would set the value of the custom property to the value of the control.

The following examples demonstrate how to work with custom document properties to store the state of a check box control:

First, in the SmartDocInitialize method, the code loops through the properties in the document to see whether the custom property "CheckboxState" exists. If the custom property doesn't exist, it creates a new "CheckboxState" custom property that stores a Boolean value, with an initial value of True.

Private Sub ISmartDocument_SmartDocInitialize(ByVal ApplicationName As String, _
        ByVal Document As Object, ByVal SolutionPath As String, ByVal SolutionRegKeyRoot As String)
    Dim objDoc As Word.Document
    Dim objProp As Office.DocumentProperty
    Dim blnExists As Boolean
    
    Set objDoc = Document
    
    For Each objProp In objDoc.CustomDocumentProperties
        If objProp.Name = "CheckboxState" Then
            blnExists = True
            Exit For
        Else
            blnExists = False
        End If
    Next
    
    If blnExists = False Then
        objDoc.CustomDocumentProperties.Add Name:="CheckboxState", _
            LinkToContent:=False, Type:=msoPropertyTypeBoolean, value:="True"
    End If
End Sub

Next, in the PopulateCheckbox method, the code again loops through the custom document properties looking for the property named "CheckboxState." After the property is found, the code sets the value of the Checked parameter to the value of the property. Note that the property that you create in the SmartDocInitialize method can be a Boolean, a date, a Float, a number, or a String. For more information about using the custom document properties, see VBA Help.

            Dim objProperty As Office.DocumentProperty

            For Each objProperty In ActiveDocument.CustomDocumentProperties
                If objProperty.Name = "CheckboxState" Then
                    Checked = objProperty.value
                    Exit For
                End If
            Next

Finally, in the OnCheckboxChange method, the code loops through the custom document properties again, looking for the property named "CheckboxState." When the code finds this property, the code sets the value of the custom property to the value of the Checked parameter.

            Dim objProperty As Office.DocumentProperty

            For Each objProperty In ActiveDocument.CustomDocumentProperties
                If objProperty.Name = "CheckboxState" Then
                    objProperty.value = Checked
                    Exit For
                End If
            Next

For more information about custom document properties, see Working with Document Properties on MSDN.