用C++和XML建立Office智能文档之三

来源：作者：出处：巧巧读书 2006-06-05 进入讨论组

引用:http://www.qqread.com/vc/d493117002.html

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。