Object Model Improvements for Smart Tags

In addition to the MOSTL improvements, version 2 of the smart tag object model has been upgraded. The main differences between version 1 and version 2 of the object model are additional capabilities using new interfaces. Version 2 is backward-compatible with version 1, so you can build version 1 smart tags using the new object model or upgrade existing smart tags to version 2 without breaking applications. The following sections describe the enhancements to the smart tag object model. All of the capabilities you saw in MOSTL files can be implemented in smart tag DLLs as well.

ISmartTagRecognizer2 Interface

Some additions to smart tags, such as property pages and better localization support, require updates to the recognizer interface. For this reason, version 2.0 of the library includes an ISmartTagRecognizer2 interface. If you implement this interface in your smart tag, the smart tag will ignore an implementation of the ISmartTagRecognizer interface. Table 9-7 lists the changes in the ISmartTagRecognizer2 interface

Table 9-7: Changes in the ISmartTagRecognizer2 Interface

Method or Property	Description
DisplayPropertyPage	A method that takes the smart tag ID and the locale ID. In this method, you write code to display a property page for your smart tag so users can customize it or obtain more information about it.
PropertyPage	A Boolean property that takes the smart tag ID and locale ID and returns a value indicating whether the smart tag supports a property page. If you return False , the Properties dialog box in the Office applications for the smart tag will be disabled.
Recognize2	A method that recognizes the terms in the document. It passes six parameters. The first is a string that is the text that should be recognized. The second is an enumeration specifying the data type for the text. For example, the enumeration can specify whether the text is sent one character at a time or as a word, or is an Excel cell . The third parameter is the locale ID of the text. The fourth parameter is a RecognizerSite2 object that allows you to interact with the smart tag host. (The RecognizerSite2 object is described later in this chapter.) The fifth parameter is the name of the application as a string, such as word.application.11 . The final parameter is the token list as an ISmartTagTokenList collection. This collection type is explained later in the chapter.
SmartTagInitalize	A method that is called when your smart tag is initializing for the first time. It takes the application name as a string. This method allows you to do any initialization work you need to do for your smart tag, such as loading data or initializing variables .

ISmartTagAction2 Interface

To support some of the enhancements for smart tag actions such as dynamic caption naming and hiding smart tag user interface indicators, you should use the new ISmartTagAction2 interface for your action DLLs. Table 9-8 describes the elements of this interface.

Table 9-8: Elements of the ISmartTagAction2 Interface

Element	Description
InvokeVerb2	A method that is called when a verb is invoked. The method allows you to implement the functionality for that verb. The method is passed seven parameters. The first is the VerbID. The second is the application name of the host, such as word.application.11 . The third is an object that is the application-specific object responsible for calling the action. In Excel, this is a Cell object, and in Word, this is a Range object. The next parameter is the property bag passed by the recognizer or by the action itself. The next parameter is the text of the smart tag. The sixth parameter is an XML representation of the smart tag. The final parameter is the locale ID.
IsCaptionDynamic	A Boolean property used for dynamic smart tag action naming. For example, you might want to change the caption of an action on the basis of a number of factors. Smart tag hosts use this property to determine whether your action is dynamic. This property is passed the VerbID, the application name, and the locale ID. From these parameters, you can return True if your verb caption is dynamic or False if it is not.
ShowSmartTagIndicator	A Boolean property that specifies whether to show the smart tag underlining. This property is passed the VerbID, the application name, and the locale ID. Passing back True shows the underlining; False does not.
SmartTagInitialize	A method that allows you to do any initialization for your actions. The method is passed the application name as a string.
VerbCaptionFromID2	A string value that specifies the caption to use for your action in the Actions drop-down list. This call passes seven parameters. The first is the VerbID, which is identified by the VerbID that is the unique identifier for the verb. The second parameter is the application name of the smart tag host. The third parameter is the locale ID. The fourth parameter is the properties set by the recognizer as a ISmartTagProperties collection. The fifth parameter is the text recognized by the recognizer. The sixth parameter is the smart tag as an XML string. The seventh parameter is the target, such as an Excel Cell object or Word Range object.

ISmartRecognizerSite2 Interface

To support passing the new interfaces when you commit smart tags, the ISmartTagRecognizerSite interface has been updated to the ISmartTagRecognizerSite2 interface. Table 9-9 explains the enhancements to this interface.

Table 9-9: Enhancements to the ISmartTagRecognizerSite2 Interface

Method

Description

CommitSmartTag2

Creates a new smart tag in the host. You must pass four parameters to this method. The first is the smart tag type string, which must be in the format namespaceURI# tagname . The second is an integer value that indicates the location at which to start the smart tag in the text. The underlining in Word for the smart tag will begin at this location. The next parameter is an integer that indicates the number of characters the smart tag will span. The final parameter is a property bag object that you want to include with the smart tag.

ISmartTagToken Interface

To support localization and easier word breaking, the smart tag 2.0 library can tokenize input so that you can implement multilingual smart tags. The ISmartTagToken , ISmartTagTokenList , and ISmartTagTokenProperties interfaces work together to support tokenization of input. Table 9-10 shows the ISmartTagToken interface's methods and properties, which represent an individual token of input.

Table 9-10: Elements of the ISmartTagToken Interface

Element	Description
Length	A long property that returns the length of the token.
Properties	An ISmartTagTokenProperties collection for arbitrary properties on the token.
Start	The position in the range of text at which the token started. This property is a long value.
Text	A string value that is the text of the token.

ISmartTagTokenList Collection

ISmartTagTokenList is a collection of ISmartTagToken objects. Table 9-11 lists the properties and methods for this collection.

Table 9-11: Elements of the ISmartTagTokenList Collection

Element	Description
Count	Returns the number of tokens in the list.
Item	Takes the index of the token as a number and returns the ISmartTagToken object that corresponds to that index.

ISmartTagTokenProperties Collection

The ISmartTagTokenProperties collection is a property bag for your tokens. It allows you to save arbitrary properties on your token for your application's custom use. Table 9-12 describes the elements of the ISmartTagTokenProperties collection.

Table 9-12: Elements of the ISmartTagTokenProperties Collection

Element	Description
Count	Returns the number of properties in the collection.
KeyFromIndex	Returns a string for the key of the specified property, based on a numbered index that you pass. For example, if you pass 1 to this method, the key is for the first custom property in the property bag.
Read	Passes the value associated with a specific key that you pass.
ValueFromIndex	Passes back the value of a property that's based on an index into the collection that you pass.