ISmartDocument接口教程
下一步是建立智能文档操作DLL并安装它。在你编写智能文档操作处理程序DLL（它实现了ISmartDocument接口方法）之前，最好先了解一下这个接口。
当用户在文档中移动的时候，你的操作处理程序DLL将建立并管理一组出现在文档操作事务面板中的控件，允许你基于文档中的位置提供自定义的用户界面。映射到文档的XML大纲元素定义了用户在文档中的位置。XML元素应该指定给用户显示哪些控件。图2显示了你可以建立的控件类型。你将使用操作处理程序DLL中实现的ISmartDocument接口的方法建立这些控件。当这些控件被激活的时候（例如进入了文本框或者点击了某个按钮），Office通过ISmartDocument接口方法调用你的自定义操作处理程序DLL代码。
图2.智能文档控件类型
符号名称 | 控件类型 | | C_TYPE_LINK | 超级链接 | | C_TYPE_HELP | 作为HTM帮助文本提供的，并显示在文档操作事务面板中 | | C_TYPE_HELPURL | 显示在文档操作事务面板中的URL-to-HTML帮助文本 | | C_TYPE_SEPARATOR | 仅仅格式化可以使用的分隔线 | | C_TYPE_BUTTON | 触发操作的命令按钮 | | C_TYPE_LABEL | 显示的静态文本 | | C_TYPE_IMAGE | 显示的图像文件，需要提供GIF、BMP、TIFF、JPEG、WMF或其它图像文件的路径 | | C_TYPE_CHECKBOX | 检查框 | | C_TYPE_TEXTBOX | 用于输入文本的编辑框 | | C_TYPE_LISTBOX | 可滚动的列表框 | | C_TYPE_COMBO | 组合框 | | C_TYPE_ACTIVEX | ActiveX 控件 | | C_TYPE_DOCUMENT- FRAGMENT | 文档片段，只能提供Word XML文本 | | C_TYPE_DOCUMENT- FRAGMENTURL | 文档片段，只能提供文件的链接 | | C_TYPE_RADIOGROUP | 单选框 |
把IsmartDocument接口的方法分为几类：配置方法，它为Office描述了建立在文档操作事务面板中的控件（图3）；控件绘制时（draw-time）方法，它们作为控件调用并绘制在事务面板上（图4）；修改通知方法，Office把它们作为文档操作事务面板控件调用，由用户维护（图5）。
图3. ISmartDocument接口配置方法
方法 | 参数 | 描述 | | SmartDocInitialize | BSTR ApplicationName, LPDISPATCH Document, BSTR SolutionPath, BSTR SolutionRegKeyRoot | 当用户打开智能文档的时候被Office调用。它可以被用户执行预先部分的初始化。IDispatch 指向被打开的Word或Excel文档。SolutionPath 是安装解决方案的本地计算机的目录名称。 | | get_SmartDocXmlTypeCount | int * Count | 为Office提供智能文档中XML元素的数量，它们必须在文档操作面板中拥有内容。每个文档元素和控件都被指定一个从1开始的智能文档类型的唯一ID（在下面的方法中叫做SmartDocID）。 | | get_SmartDocXmlTypeName | int SmartDocID, BSTR * bstrElementName | 为Office提供与SmartDocID对应的XML元素名称（从1开始）。 | | get_SmartDocXmlTypeCaption | int SmartDocID, int LocaleID, BSTR * Caption | 为Office提供与SmartDocID 对应的元素名称在文档事务面板中显示的本地化说明。你必须在从DLL中的本地字符串表中载入它。 | | get_ControlCount | BSTR bstrElementName, int * Count | 给定一个来自智能文档的XML元素名称，告诉Office当用户位于文档中某个位置的时候，在文档操作事务面板中将显示多少个控件。 | | get_ControlID | BSTR bstrElementName, int ControlIndex, int * ControlID | 给定一个元素名称和一个控件索引（从1开始），你使用该方法赋予每个控件一个唯一的控件ID。该方法的其它部分用这个ID引用控件。 | | get_ControlNameFromID | int ControlID, BSTR * Name | 给定一个控件ID，提供控件的（内部）名称。 | | get_ControlTypeFromID |
int ControlID, BSTR ApplicationName, int LocaleID, C_TYPE * Type | 给定一个控件ID，提供控件的类型（图2显示了类型列表）。 |
图4. ISmartDocument接口控件绘制方法
方法 | 参数 | 描述 | | get_ControlCaptionFromID | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, BSTR * Caption | 提供给定的控件ID的可视的控件名称（作为输出BSTR）。 | | PopulateHelpContent | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, BSTR * Content | 供C_TYPE_HELP或C_TYPE_HELPURL类型的控件调用以提供帮助文本。 | | PopulateCheckbox | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, VARIANT_BOOL * Checked | 供C_TYPE_ CHECKBOX类型的控件调用以提供检查框的状态。 | | PopulateTextboxContent | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, BSTR * Value | 供C_TYPE_TEXTBOX类型的控件调用以提供文本框的内容（在输出参数的BSTR值中）。 | | PopulateListOrComboContent | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, SAFEARRAY * * List, int * Count, int * InitialSelected | 供C_TYPE_LISTBOX或C_TYPE_COMBO类型的控件调用以提供下拉框或组合框的内容。其内容作为List输出参数的一个VARIANT数组提供；数组中数据项的数量由Count 输出参数提供；最初的选择（从1开始）由InitialSelected 输出参数提供（如果没有选择返回－1）。 | | PopulateDocumentFragment | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, BSTR * DocumentFragment | 仅仅被Word使用。供C_TYPE_DOCUMENTFRAGMENT类型的控件调用以提供文档片段的内容（作为HTML形式）。 | | PopulateActiveXProps | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, ISmartDocProperties * ActiveXPropBag | 供C_TYPE_ACTIVEX类型的控件调用以提供初始化事务面板中的ActiveX 控件需要的信息。这些信息是通过IPropertyBag 提供的。 | | PopulateImage | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, BSTR * ImageSrc | 供C_TYPE_IMAGE类型的控件调用以提供图像的路径（本地路径、UNC或URL）。图像可以是GIF、 JPEG或WMF。 | | PopulateRadioGroup | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props, SAFEARRAY * * List, int * Count, int * InitialSelected | 供C_TYPE_RADIOGROUP类型的控件调用以提供单选按钮的内容。这些都作为VARIANT数组中的BSTR字符串、数组中数据项的数量、最初的选择（从1开始）提供的。 | | PopulateOther | int ControlID, BSTR ApplicationName, int LocaleID, BSTR Text, BSTR Xml, LPDISPATCH Target, struct ISmartDocProperties * Props | 供 C_TYPE_LINK和C_TYPE_BUTTON类型的控件调用以提供超级链接的内容。这些都作为VARIANT数组中的BSTR字符串、数组中数据项的数量、最初的选择（从1开始）提供的。 | | OnPaneUpdateComplete | LPDISPATCH Target | 当控件绘制好后被调用。 |
图5. ISmartDocument接口通知方法
| 方法 | 参数 | 描述 | | InvokeControl | int ControlID, BSTR ApplicationName, LPDISPATCH Target, BSTR Text, BSTR Xml, int LocaleID | 当用户按下按钮或点击文档片段中的链接的时候，为C_TYPE_LINK、 C_TYPE_BUTTON、C_TYPE_DOCUMENTFRAGMENT和C_TYPE_DOCUMENTFRAGMENTURL 类型的控件调用它。 | | OnCheckboxChange | int ControlID, LPDISPATCH Target, VARIANT_BOOL Checked | 当复选状态改变的时候，为C_TYPE_CHECKBOX类型的控件调用它。 | | OnTextboxContentChange | int ControlID, LPDISPATCH Target, BSTR Value | 当文本内容发生改变的时候，为 C_TYPE_TEXTBOX类型的控件调用它。 | | OnListOrComboSelectChange | int ControlID, LPDISPATCH Target, int Selected, BSTR Value | 当被选中的数据项发生改变的时候，为C_TYPE_LISTBOX或C_TYPE_COMBO类型的控件调用它。 | | ImageClick | int ControlID, BSTR ApplicationName, LPDISPATCH Target, BSTR Text, BSTR Xml, int LocaleID, int XCoordinate, int YCoordinate | 当用户点击图像的时候，为C_TYPE_IMAGE类型的控件调用它。X和Y 都是从0开始的，与图像左上角的相对象素。 | | OnRadioGroupSelectChange | int ControlID, LPDISPATCH Target, int Selected, BSTR Value | 当用户改变单选框的选择状态时，为C_TYPE_RADIOGROUP类型的控件调用它。字符串的值是被最新选择的数据项的文本。 |
注意，对于大多数DLL，你不会使用所有的控件类型或实现所有的IsmartDocument方法。例如，因为我的事务面板中没有ActiveX或列表框控件，在例子中就只有这些方法的样板实现。甚至于根本不编写任何操作处理程序DLL也可能利用一些简单的智能文档特性（例如提供超级链接或内容敏感性帮助文本）。作为代替的是你只需要在关联的Word或Excel智能文档中简单地提供一个XML文件，该文件描述了你希望与多种XML元素关联的操作。
图6摘录了ISmartDocument方法的参数。
图6. ISmartDocument通用方法参数
| 参数 | 描述 | | BSTR ApplicationName | 寄宿智能文档的Office 应用程序的ProgID （例如"Excel.Application.11"）。 | | LPDISPATCH Document | 或Target 指向下层的Word 或Excel文档的IDispatch指针（供SmartDocInitialize和 OnPaneUpdateComplete使用）。对于其它方法，IDispatch指向受到影响的XML元素的Word或Excel范围。 | | int LocaleID | 用户语言的LCID ；供多语言智能文档使用，以激活从DLL中载入的本地化的字符和其它资源。 | | ISmartDocProperties * Props | 用于提供控件属性的IPropertyBag。 | | BSTR Text | 当前文档元素的文本。 | | BSTR Xml | 文档元素的XML表现方式，不能为NULL。 |
|