Adding Help Content (Visual C++ Tutorial) [Office 2003 SDK Documentation]

Article
01/16/2009

The following steps show you how to add a collection of radio buttons to the SimpleSample smart document. In this section, you add two portions of Help text to the SimpleSample smart document. The first portion displays the Help globally for all elements and is attached to the top-level example element. The second portion displays Help text for the help element.

The first thing you need to do is add constants for the example and help elements in the SimpleSample schema. Insert the following code into the general declarations section of your code module, below the existing constants.
```
    #define  cEXAMPLE(xmlns) xmlns L"#example"
    #define  cHELP(xmlns) xmlns L"#help"
```
Next, you need to add 2 to the cTYPES constant. Remove the existing cTYPES constant, and enter the following code or change your code to match.
```
    #define cTYPES 4
```
You also need to add two variables: One contains a reference to the smart document document object, and the other contains the path to your smart document solution. In the case of the SimpleSample smart document, the path is a location on your local computer. However, you can also host a smart document on a Web server or on a shared network location. Insert the following global variables. You specify the value of the path variable in the SmartDocInitialize subroutine.

Variable Type Variable Name

_Document m_objDoc

CComBSTR m_bstrPath

How?
- Right-click the CActions class in the Class View.
- Click Add Member Variable.
- Type _Document in the Variable Type text box.
- Type m_objDoc in the Variable Name text box.
- Click OK.
- Repeat the preceding steps to add the m_bstrPath variable.
To get a pointer to the location of the Help files, you need to specify the folder. However, because you may not know where the files are located on a user's local computer, you are using a relative path based on the value of the Path property of the smart document's Document object. You do this by accessing the Microsoft Office Word 2003 Visual Basic for Applications (VBA) object model.

Note To work with the VBA object model, you must add a reference to the Microsoft Word 11.0 Object Library.

How?
1. On the View menu, click Class Wizard.
2. Click Add Class, and then click From a type library.
3. Navigate to MSWORD.olb (usually located at C:\Program Files\Microsoft Office\OFFICE11), and then click Open.
4. In the Confirm Classes dialog box, click the following classes: _Application, _Document, InlineShapes, Range, Selection, SmartTag, SmartTagActions, View, Window, XMLNode, and XMLNodes. To select multiple items in the list, hold down the CTRL key while clicking. (Note The items in this list are not alphabetized.)
5. Click OK. (A warning message may be displayed saying that a file was modified externally; click Yes, and then close the Class Wizard dialog box.) You now have a new file named msword.cpp in your list of source files.
6. At the top of the Actions.h file, add the following line.
```
#include "msword.h"
```

Variable Type	Variable Name
_Document	m_objDoc
CComBSTR	m_bstrPath

Insert the following code in the SmartDocInitialize subroutine that you added earlier.

        if (m_objDoc.m_lpDispatch != NULL)
        {
            m_objDoc.DetachDispatch();
            m_bstrPath.Empty();            
        }

        m_objDoc.AttachDispatch(Document);            
        m_bstrPath.Append(m_objDoc.GetPath());
        m_bstrPath.Append("\\");

        return S_OK;

Next you add the destructor for the class to destroy the m_objDoc object variable. To do this, open the Actions.h file, and then insert the following code directly below the class constructor.
```
    ~CActions()
    {
        m_bstrPath.Empty();

        if (m_objDoc.m_lpDispatch !=NULL)
            m_objDoc.DetachDispatch();
    }
```

Now you are ready to modify the existing code to insert the Help text. The subroutines you need to modify are SmartDocXMLTypeName, SmartDocXMLTypeCaption, ControlCount, ControlID, ControlTypeFromID, and ControlCaptionFromID.

In the SmartDocXMLTypeName property subroutine, insert the following code.

            case 3:
                *Name = SysAllocString(cEXAMPLE(cNAMESPACE));
                break;

            case 4:
                *Name = SysAllocString(cHELP(cNAMESPACE));
                break;

In the SmartDocXMLTypeCaption property subroutine, insert the following code.

            case 3:
                *Caption = SysAllocString(L"Global help text");
                break;

            case 4:
                *Caption = SysAllocString(L"Help text");
                break;

In the ControlCount property subroutine, insert the following code.

        else if (wcscmp(XMLTypeName,cEXAMPLE(cNAMESPACE)) == 0)
        {           
            *Count = 1;
        }
        else if (wcscmp(XMLTypeName,cHELP(cNAMESPACE)) == 0)
        {           
            *Count = 1;
        }

In the ControlID property subroutine, insert the following code.

        else if (wcscmp(XMLTypeName,cEXAMPLE(cNAMESPACE)) == 0)
        {           
            *ControlID = ControlIndex + 200;
        }
        else if (wcscmp(XMLTypeName,cHELP(cNAMESPACE)) == 0)
        {           
            *ControlID = ControlIndex + 300;
        }

In the ControlTypeFromID property subroutine, insert the following code. When you specify the control type, use the C_TYPE_HELP constant to specify Help content that is in the code and is passed as a string; use the C_TYPE_HELPURL constant to specify Help content that is pulled from an external file and is passed as a file path. Help content, whether contained in the code or in an external file, should be well-formed HTML or XHTML.

            case 201:
                *Type = C_TYPE_HELP;
                break;

            case 301:
                *Type = C_TYPE_HELPURL;
                break;

In the ControlCaptionFromID property subroutine, insert the following code.

            case 201:
                *Caption = SysAllocString(L"Help text applies to all elements.");
                break;

            case 301:
                *Caption = SysAllocString(L"Help text applies only to the help element.");
                break;

Now you add the code to populate the Help text. Use the PopulateHelpContent method to specify Help content. As noted above, one of the Help portions is specified by using the C_TYPE_HELP constant, and the other is specified by using the C_TYPE_HELPURL constant. Insert the following code into the PopulateHelpContent method subroutine.

Note Not all HTML elements are supported for Help content displayed in the Document Actions task pane. For information about which elements are supported, see Formatting HTML Help Content.
```
        CComBSTR bstrContent(m_bstrPath.m_str);

        switch (ControlID)
        {
            case 201:
                *Content=SysAllocString(L"<html><body><p>This is the SimpleSample smart document.</p></body></html>");
                break;
            case 301:                
                bstrContent.Append(L"help.htm");
                bstrContent.CopyTo(Content);
                bstrContent.Empty();
                break;
        }

        return S_OK;
```
Recompile your SimpleSample smart document DLL, and copy it to the deployment location that you specified earlier. When you reopen your SimpleSample smart document, delete the SimpleSample XML expansion pack, and then re-add it to the document.

Next Adding Radio Buttons

Adding Help Content (Visual C++ Tutorial) [Office 2003 SDK Documentation]

How?

How?

Additional resources