Search Wiki:

Script Object Model

The following object models are provided to:
- <scriptCondition> condition
- <ruleScript> rule generator
- <script> executor

Objects List
Application
ChooseFromList
Command
CommandSet
Debug
NamedStates
RuleItem
RuleItemCollection
Rule
Condition


Application object

The Application object contains methods that parallel the Executors available to the Command Set. This allow <script> executors to perform the same functionality as any other executor.
Methods
SetTextFeedback
The SetTextFeedback method is used to set the text in the Speech Recognition UI.
Parameter Name Type Default Value Description
Text BSTR no default value Text to be displayed in the Speech Recognition Feedback Window
Warning BOOL FALSE Show the message as a warning
Speak BOOL FALSE Speak the text in addition to displaying it
Return Value: None.

Alert
The Alert method brings a dialog box with a message.
Parameter Name Type Default Value Description
Prompt BSTR no default value Text to be displayed in the dialog box
Title BSTR <empty> Text to be displayed in the dialog box title
Timeout FLOAT 0.0 Time in seconds before the window atuomatically closes. 0 indicates that it never timeout
Return Value: None.

Confirm
The Confirm method brings up a dialog box with a message and "Yes" and "No" buttons.
Parameter Name Type Default Value Description
Prompt BSTR no default value Text to be displayed in the dialog box
Title BSTR <empty> Text to be displayed in the dialog box title
Timeout FLOAT 0.0 Time in seconds before the window atuomatically closes. 0 indicates that it never timeout
Return Value: Integer of the Button "6" for IDYES, "7" for IDNO or -1 if dialog times out.

MsgBox
The MsgBox method brings up a dialog box with user specified content
Parameter Name Type Default Value Description
Prompt BSTR no default value Text to be displayed in the dialog box
Title BSTR <empty> Text to be displayed in the dialog box title
Timeout FLOAT 0.0 Time in seconds before the window atuomatically closes. 0 indicates that it never timeout
Buttons Int 0 Button arguments for VBscript MsgBox
Return Value: None.

(for more info on the Buttons parameter read the VBscript documentation here http://msdn.microsoft.com/en-us/library/sfw6660x.aspx)

Prompt
The Prompt method brings a dialog box with an edit control allowing the user to enter text
Parameter Name Type Default Value Description
Prompt BSTR no default value Text to be displayed in the dialog box
initialValue BSTR 0 Default text in the edit control
Title BSTR <empty> Text to be displayed in the dialog box title
Timeout FLOAT 0.0 Time in seconds before the window atuomatically closes. O indicates that it never timeout
Return value: BSTR containing the text entered by the user. If the user cancels the dialog box or it times out, the returned value is an empty string.

Run
The Run method launches an application or URL
Parameter Name Type Default Value Description
Command BSTR no default value URL or executable file name to run
Params BSTR <empty> Command line arguments
startInDirectory BSTR <empty> Working directory for the application
Return value: None. If the URL or application fails to launch an exception will be thrown.

SwitchToAppByTitle
The SwitchToAppByTitle method brings the specified application window to the foreground.
Parameter Name Type Default Value Description
Title BSTR no default value Window Title of the application
ExactMatch BOOL FALSE Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.

MinimizeAppByTitle
The MinimizeAppByTitle method minimizes the specified application window.
Parameter Name Type Default Value Description
Title BSTR no default value Window Title of the application
ExactMatch BOOL FALSE Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.

MaximizeAppByTitle
The MaximizeAppByTitle method maximizes the specified application window.
Parameter Name Type Default Value Description
Title BSTR no default value Window Title of the application
ExactMatch BOOL FALSE Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.


RestoreAppByTitle
The RestoreAppByTitle method restores the specified application window.
Parameter Name Type Default Value Description
Title BSTR no default value Window Title of the application
ExactMatch BOOL FALSE Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.

CloseAppByTitle
The CloseAppByTitle method closes the specified application window.
Parameter Name Type Default Value Description
Title BSTR no default value Window Title of the application
ExactMatch BOOL FALSE Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.

SendMessage
The SendMessage method provides limited means to send window messages to a window.
Parameter Name Type Default Value Description
className BSTR no default value Name of the window class of the target window
windowName BSTR no default value Title of the target window
Msg UINT no default value Window message number
wParam UINT no default value wParam value of message
lParam UINT no default value lParam value of message
Return Value: UINT result of SendMessage. This value is application specific.

SendKeys
The SendKeys method sends keystrokes to the foreground window.
Parameter Name Type Default Value Description
Keys BSTR no default value Keys to send to the foreground window
Return Value: None. An exception will be thrown if an error ocurred.
Note: Visit the <sendKeys> executor documentation for details regarding the string format for Keys.

InsertText
The InsertText method inserts the specified text into t he foreground window.
Parameter Name Type Default Value Description
text BSTR no default value Text to send to the foreground window
Return Value: None. An exception will be thrown if an error ocurred.

EmulateRecognition
The EmulateRecognition method sends a string of Windows Speech Recognition commands to the recognizer.
Parameter Name Type Default Value Description
textToEmulate BSTR no default value Text that represents WSR commands to be sent to the recognizer
disambiguationTimeout FLOAT 0.0 Time to wait for native disambiguation to occur. 0.0 indicates that disambiguation is not expected
Return Value: None. An exception will be thrown if an error ocurred.

Speak
The Speak method causes the TTS engine to speak the text provided.
Parameter Name Type Default Value Description
Text BSTR no default value Text to be spoken
Flags ULONG 16 (SPF_IS_NOT_XML) SPEAKFLAGS passed to the TTS engine
Return Value: None. An exception will be thrown if an error ocurred.
Note: For more information about SPEAKFLAGS go to http://msdn.microsoft.com/en-us/library/ms717252(VS.85).aspx

Wait
The Wait method pauses execution for a specified time period.
Parameter Name Type Default Value Description
Seconds FLOAT 1.0 Time in seconds to stop execution
Return Value: None. An exception will be thrown if an error ocurred.

Properties
clipboardData
The clipboardData property is a read-only property that returns the clipboardData object.


clipboardData object

The clipboardData object can be used to manipulate text data in the system clipboard.

Methods
getData
The getData method of the clipboardData object returns the text currently contained in the systems clipboard.
Parameter Name Type Default Value Description
Format BSTR no default value Clipboard format string (only text is supported)
Return Value: VARIANT - The text currently in the clipboard, or an empty string if no clipboard text exists.

setData
The setData method of the clipboardData object places the specified text into the system clipboard.
Parameter Name Type Default Value Description
Format BSTR no default value Clipboard format string (only text is supported)
Data VARIANT no default value Text to place into the system clipboard
Return Value: None. An exception will be thrown if an error occurs.

clearData
The clearData method of the clipboardData object clears any text from the systems clipboard.
Parameter Name Type Default Value Description
Format BSTR no default value Clipboard format string (only text is supported)
Return Value: None. An exception will be thrown if an error occurs.


ChooseFromList object


Methods
Choose
The Choose method of the ChooseFromList object launches a dialog window with a list that allows the user to choose from the selection.
Parameter Name Type Default Value Description
Prompt BSTR <empty> Text that prompts the user. This will be displayed at the top of the dialog box
Title BSTR <empty> Title of the dialog window
Timeout FLOAT 0.0 Time to wait (in seconds) before automatically canceling the dialog window. 0.0 indicates that it never times out
Return Value: int - The zero-based index of the item selected by the user. If user cancels or dialog timesout -1 is returned.
Note: The Items property of the ChooseFromList must be initialized to contain the itemos to be presented in a list to the user.

Properties
Items (read-only)
The Items property of the ChooseFromList object is a RuleItemCollection object containing the choices to be presented in a list to the user. This
property may be set using an external RuleItemCollection (from a rule generator, for example) or it may be directly modified.

Command object


Methods
ResolveProperties
The ResolveProperties method of the Command object provides a mean to get the value of a named property. This property can be any property that would normally be resolved
using the {[property]} syntax.
Parameter Name Type Default Value Description
PropertyString BSTR no default value Property to be resolved
Return Value: The resolved property string. If a property specified in the string does not exists it is replaced with an empty string.

Exit
The Exit method causes the script to terminate. This can be useful for early termination fo a script, and also to halt the list of executors in a command.
Parameter Name Type Default Value Description
ExitCode DWORD no default value A non-zero value in this field causes the current executor to stop execution. Zero allows the executor to continue execution.
Return Value: None. An exception will be thrown if an error ocurred.

Properties
Result (read-only)
The Result object is the ISpRecoResult returned from the recognizer for the recognition event that triggered this executor. Click the following link for more information:
http://msdn.microsoft.com/en-us/library/ms718929(VS.85).aspx


CommandSet object

The CommandSet object contains methods used to access Conditions or Rule Generators within the Command Set.
Methods
Conditions
Parameter Name Type Default Value Description
ConditionName BSTR no default value Name of the Condition
Return Value: The Condition method returns an object dependent on the type of the condition targeted. Different conditions support different methods and properties. All
Conditions support the Attributes property which is an IXMLDOMNamedNodeMap representing the XML attribute of the XML node representing the condition.

RuleGenerators
Parameter Name Type Default Value Description
RuleName BSTR no default value Name of the Rule Generator
Return Value: The RuleGenerator methods returns an obect dependent on the type of the Rule Generator targeted. Different rule generators support different methods
and properties, The table below illustrates which properties are available for each Rule Generator:

Attributes: IXMLDOMNamedNodeMap containing the XML attributes of the Rule Generator.
Rule: Rule object of the rule.
Script: <ruleScript> only: Collection of objects and functions within a <ruleScript> script.
Text: <listenFor> only. Text of the <listenFor> element.
Rule Generator Attribute Rule Script Text
<fileNames> X X
<fontNames> X X
<listenForList> X X
<listenFor> X X
<numbers> X
<ruleScript> X X X
<rule> X
<wmpMediaItems> X X


Debug object

The Debug object is made available to aid in debugging scripts within Command Sets.
Methods
Assert
Parameter Name Type Default Value Description
Test BOOL no default value If FALSE a dialog box pops with the Prompt text. If TRUE execution runs normally
Prompt BSTR no default value Text displayed in the dialog box if Test evaluates to FALSE
Return Value: None.

DebugBreak
The DebugBreak method is used to halt execution of a script in the debugger. If a debugger is not running, the user will be prompted to choose a debugger to
attach to the process.
Parameters:None.
Return Value: None.

Trace
The Trace method is used to output a message to a debugger window.
Parameter Name Type Default Value Description
Text BSTR no default value Text to be sent to the debugger output window
Return Value: None.

NamedStates object

The NamedStates object is used to interact with Named States in the system. These can be set either through this methods of this object or by the <setState> executor.
Methods
IsNamedStateSet
The IsNamedStateSet method checks the value of a Named State. If a value exists and is not empy, this methods returns true.
Parameter Name Type Default Value Description
StateName BSTR no default value Name of the state to check
Return Value: TRUE if the specified state is non empty. FALSE otherwise.

IsNamedStateSetToValue
The IsNamedStateSetToValue method checks the value of a Named State against a specified value. If the values are identical the method returns TRUE.
Parameter Name Type Default Value Description
StateName BSTR no default value Name of the state to check
StateValue BSTR no default value Value used for comparision
Return Value: TRUE if the value of the state equals the specified value. FALSE otherwise.

SetNamedStateValue
The SetNamedStateValue method sets the value of the specified state.
Parameter Name Type Default Value Description
StateName BSTR no default value Name of the state to set
StateValue BSTR no default value Value assigned to state
Return Value: None.

GetNamedStateValue
The GetNamedStateValue method retrieves the value of the specified state.
Parameter Name Type Default Value Description
StateName BSTR no default value Name of the state to be retrieved
Return Value: BSTR The value of the specified Named State. If the state is not set an empty string will be returned.

ClearNamedStateValue
The ClearNamedStateValue method clears the value of the specified state.
Parameter Name Type Default Value Description
StateName BSTR no default value Name of the state to clear
Return Value: None.

WaitForAllNamedStatesToBeSet
The WaitForAllNamedStatesToBeSet method pauses execution of the script until all the specified states are set (non-empty) or the specified timeout expires.
Parameter Name Type Default Value Description
StateList BSTR no default value List of states to wait for. States are separated by the vertical bar "" symbol
Timeout FLOAT no default value Time in seconds to wait for the specified states to be set
Return Value: BOOL - TRUE if all states were set FALSE if timeout expires.

WaitForAnyNamedStateToBeSet
The WaitForAllNamedStateToBeSet method pauses execution of the script until one or more of the specified states are set (non-empty) or the specified timeout expires.
Parameter Name Type Default Value Description
StateList BSTR no default value List of states to wait for. States are separated by the vertical bar "" symbol
Timeout FLOAT no default value Time in seconds to wait for the specified states to be set
Return Value: BOOL - TRUE if any states were set FALSE if timeout expires.

RuleItem object

The RuleItem object represents a spoken phrase and their property value within a rule.
Methods
Clone
The Clone method creates a copy of the RuleItem object.
Parameters:None.
Return Value:A RuleItem object that is a copy of the original.

Properties
Phrase (read/write)
Type: BSTR
The Phrase property of a RuleItem object is a string that contains the text the recognizer should listen for.
Example:
myRuleItem.Phrase = "John Smith";
In this example, the recognizer listens for "John Smith".

Property (read/write)
Type:BSTR
The Property property of the RuleItem object is the semantic property associated with t he item.
Example:
myRuleItem.Phrase = "John Smith";
myRuleItem.Property = "johnsmith@email.com";
In this example, the recognizer listens for "John Smith" and sets the semantic property of the rule to "johnsmith@email.com".

UseSubsets (read/write)
Type:BOOL
The UseSubsets property of the RuleItem object indicates if the recognizer should accept an ordered subset of the words contained in the Phrase property rather than the entire set of words.
Example:
myRuleItem.Phrase = "John Austin Smith Junior";
myRuleItem.Property = "johnsmith@email.com";
myRuleItem.UseSubsets = true;
In this example, setting UseSubsets to true allows the recognizer to listen for "John Austin", "Austin Junior", "John Smith" to match this rule item. If UseSubsets property were set to false only "John Austin Smith Junior" would be recognized to match the RuleItem.

RuleItemCollection object

The RuleItemCollection object is a container class used to hold a collection of RuleItem objects.
Methods
NewEnum
The NewEnum method is used to allow VBScript enumerations internally, and is not normally called from within script.
Parameters:None.
Return Value:IEnumVariant - A new enumerator which can be used to iterate through the items of the collection. Visit the following website for more information http://msdn.microsoft.com/en-us/library/ms221053.aspx

FindTextMatches
The FindTextMatches method returns a new RuleItemCollection containing items from the original collection that contain the ordered subset specified in the Filter parameter.
Parameter Name Type Default Value Description
Filter BSTR <empty> Ordered subset used to filter matches. If this value is an empty string a complete copy of the RuleItemCollection will be returned.
Return Value: RuleItemCollection - a new collection containing the matching RuleItems.
Example:
_ var flavoredPops = popsCollection.FindTextMatches("flavored pop");_
In thsi example the flavoredPops collection would contain items from the popsCollection whose phrases contain the words "flavored" and "pop" in that order. This could include items such as:
"orange flavored pop"
"cola flavored pop"

AddItem
The AddItem method adds a new RuleItem to the collection.
Parameter Name Type Default Value Description
Phrase BSTR no default value Phrase property of the new RuleItem
PropertyValue BSTR <empty> Property property of the new RuleItem
UseSubsets BOOL FALSE UseSubsets property of the new RuleItem
Return Value: None.

AddItems
The AddItems method adds a RuleItemCollection to the collection.
Parameter Name Type Default Value Description
Collection RuleItemCollection no default value RuleItemCollection to be added
Return Value: None.

RemoveItem
The RemoveItem method removes items from the collection.
Parameter Name Type Default Value Description
Phrase BSTR no default value Phrase property of the RuleItem to be removed
PropertyValue BSTR <empty> Property property of the RuleItem to be removed
UseSubsets BOOL FALSE UseSubsets property of the RuleItem to be removed
Return Value: None.

RemoveItems
The RemoveItem method removes a collection of items from the collection.
Parameter Name Type Default Value Description
Collection RuleItemCollection no default value Collection of Items to be removed
Return Value: None.

RemoveAll
The RemoveAll method removes all items from the collection.
Parameters: None.
Return Value:None.

Sort
The Sort method sorts the items in the collection. Sorting is performed alphabetically based on the Phrase property of each RuleItem.
Parameter Name Type Default Value Description
Ascending BOOL TRUE If TRUE the collection is order in ascending order, if FALSE the collection is ordered in descending order
Return Value:None.

Properties
Item (read-only)
The Item property returns the RuleItem at the specified location.
Parameter Name Type Default Value Description
Index VARIANT No default value Zero based index of the item to be retrieved
Return Value:The RuleItem found at the specified index.

Count (read-only)
The Count property returns the number of items in the collection.
Parameters:None.
Return Value:LONG - the number of items in t he collection.

Rule object

The Rule object creates or modifies rules within a Rule Generator. Most commonly this object is used by <ruleScript> scripts to generate rules on the fly.
Methods
Commit
The Commit method causes the rule to be generated and inserted into the recognizer. The call to Commit() is optional within a <ruleScript> script.
Commit can be called again after the rule has been generated to cause the rule to be reloaded in the Command Set.
Parameters:None
Return Value:None

Properties
Items (read/write)
The Items property of the Rule object represents the RuleItemCollection of RuleItems that compose the rule. This property may be set or retrieved.
Parameters:None
Return Value:The RuleItemCollection returned by the Rule.

InnerXML (read/write)
The InnerXML property can be used to set or retrieve the SAPI XML that is sent to the recognizer. This property may be set to allow the Rule object to contain a SAPI rule. Setting the XML directly using this property causes the Items of the Rule object to be emptied, and no manipulation of the rule can be done through the Items object.
If the InnerXML property has not been explicitly set, this property returns the SAPI XML generated by the Items collection as it is sent to the recognizer.
Parameters:None.
Return Value:BSTR - The SAPI XML representing this Rule object.

RuleName (read only)
The RuleName property returns the name of the Rule. This is a read-only property. The RuleName for <ruleScript> Rule Generators is determined by the "name=" attribute of the <ruleScript> tag.
Parameters:None
Return Value:BSTR-The name of the rule.

PropName (read only)
The PropName property returns the name of the semantic property associated with items of the Rule object. The PropName for <ruleScript> Rule Generators is determined by the "propname=" attribute of the <ruleScript> tag.
Parameters:None
Return Value:BSTR-The name of the semantic properties associated with this rule.

Condition object

The Condition object is exposed to <scriptCondition> conditions. It contains methods and properties used to aid in condition evaluation.
Methods
setTimeout
The setTimeout method allows the script author to execute a scriptlet after a specified period of time has expired. Unlike setInterval, setTimeout will
only execute the scriptlet once.
Parameter Name Type Default Value Description
Seconds FLOAT no default value Time in seconds before running the scriptlet
Scriptlet BSTR no default value Scriptlet code to run
Return Value: ULONG - Timer ID. This ID can be passed to the clearTimeout method to cancel the timer.

setInterval
The setInterval method allows the script author to execute a scriptlet after a specified period of time has expired. Unlike setTimeout, setInterval executes the scriptlet code every interval until clearInterval is called.
Parameter Name Type Default Value Description
Seconds FLOAT no default value Time in seconds before running the scriptlet
Scriptlet BSTR no default value Scriptlet code to run
Return Value: ULONG - Timer ID. This ID can be passed to the clearInterval method to cancel the timer.

Properties
Satisfied (read/write)
The Satisfied property determines if the <scriptCondition> condition has been met. Set this property to TRUE to cause the condition to pass. Set to
FALSE to cause the condition to fail.
Parameters:None.
Return Value:BOOL - The current state of the condition.

Last edited Jan 30 2009 at 7:40 PM  by alex_avila, version 2
Updating...
Page view tracker