Automation Event Handling

Event Handlers

In order to respond to an event, the application needs a corresponding event procedure (also called an event handler). If an event does not have an associated procedure, then that event is not considered handled and the application does not act upon it. By default, no event procedures are included in any Visual Basic applications. For example, a programmer may include a command button on a form. But the mere presence of the button does not mean that there is an associated activity if the user clicks the button. Instead, the programmer must explicitly define the activity. In the same way SAPI returns several types of events by default. However, unless the host application has the code to process the event, it will appear that the event is not handled.

In Visual Basic, defining the procedure is simple and can be done in one of three ways.

1. Double-click the control while in design mode. Visual Basic programmer are probably most familiar with this method. For example, double-click the command button while in design mode. Visual Basic automatically includes the code necessary to support the function. This code includes the event type (again, for this example, the event type is button Click) and nay necessary parameters. In fact, programmers do not need to know the number or kinds of parameters. Visual Basic includes them automatically.

2. Use the Object or Procedures drop-down list boxes in the Visual Basic editor. The Object list presents all the available objects on the form. From this list, the programmers can directly choose the procedure they want rather than scrolling through the code or searching for the item name.

The Object Menu in Visual Basic. This lists all the objects on the form. In this example, the form only contains a single item: a button named Command1. However, the form itself is an object and can have events associated with it. By default, there is also a General item. This includes functions not associated with directly with any control.

The Procedures list presents all the events available for the selected object. Keep in mind that clicking a specific control in the forms window only brings up one kind of event, usually the click event. Objects often have many other events associated with it. New events may be added for the item selected in the Object menu. Select the intended event from the Procedures menu. Visual Basic automatically opens the code window, and includes the supporting code necessary to the event. Again, programmers do not need to know parameter information.

The Procedures menu in Visual Basic. With an object selected from the Object menu, the available events are listed. Using the previous example, the events listed are for the Command1 button. Choosing an event (the click event is highlighted) will automatically insert the subroutine or function along with the required parameters.

3. Consult the API documentation for the event. This presents the information and parameter requirements for the event. The function can then be written or pasted in manually as code. This is the least automated method of the three. However, not all development environments support automatic generation of code and this may be the only option in some cases.

In the simple case of a command button Click, any of the three methods above results in the following code:

Private Sub Command1_Click()

End Sub

Whenever Command1 is clicked, it uses the code in this routine. Naturally, it is up to programmers to write the procedure to handle the event as they see fit.

SAPI Event Handlers

Adding SAPI event handlers is similar to other controls. First, the object associated with the events must be declared. For example, declare a new recognizer object in the project

Public WithEvents RC As SpSharedRecoContext

Notice also the declaration has an additional keyword in it: WithEvents. This keyword is required to identify the object as an event source and thus allowing events to be associated with the recognition object. It may also be misleading since the application will still compile and run if it is omitted. If the key word is missing, no events will be returned. Once declared, the Procedures menu will then list the events.

With the same ease as selecting an event for a conventional control, you can select an event for the SAPI object. For instance, selecting Recognition from the Procedures menu inserts the appropriate code in the open project file.

An example of the Procedures menu with the Microsoft Speech Platform. The recognition context is declared as the RC object. The Procedures menu lists all the available events for the recognition context. The two in bold indicate those events are already defined. The other events listed will have the code generated for them if event is selected.

A Recognition event is defined as

Private Sub RecoContext_Recognition(ByVal StreamNumber As Long, ByVal StreamPosition As Variant, ByVal RecognitionType As SpeechLib.SpeechRecognitionType, ByVal Result As SpeechLib.ISpeechRecoResult)

End Sub

Events in Scripting Languages

In scripting languages, use the HTML object tag to instantiate a SAPI object. Event procedures for such an object are identified by the object-ID and the event name. For example, the following JavaScript code snippet demonstrates the definition and creation of an SpVoice object and the definition of a typical Word event procedure.

...
<OBJECT ID="VoiceObj" CLASSID="clsid:96749377-3391-11D2-9EE3-00C04F797396"></OBJECT>

<SCRIPT LANGUAGE="JScript">

function VoiceObj::Word(Number, Position, CharacterPosition,Length)
{
	idTextBox.select();			
	var CurrentRange = document.selection.createRange();
	var MyLen = CurrentRange.text.length;
	CurrentRange.moveStart("character", CharacterPosition);
	CurrentRange.moveEnd("character", CharacterPosition + Length - MyLen);
	CurrentRange.select();
	idTextBox.focus();
}
...

There are two ways for applications developers to create a recognizer and a recognition context. The first is to create a recognizer object and then to derive a recognition context from the recognizer. The other is to create a recognition context and then to derive the recognizer from the context.

But in a scripting environment, events can only be received by objects created by the scripting host. And since recognition results are received exclusively through recognition context events, consequently, in a scripting environment, the recognition context must be created first. As a further consequence, the recognizer created from the recognition context will be associated with the default SR engine.

Event Parameters

The SAPI engines return information back to the application through the event handler's parameters. SAPI events can come from different sources and there can even be multiple instances of recognition contexts or voices. However each event is self-contained and has enough information to relate the event to a specific and unique source. If the recognition context or even the recognizer itself is important, you can derive the source by tracing back information through the parameters.

In the case of a Recognition event, a common situation is that the application is interested only in the last parameter, the recognition result. This contains information about the recognized phrase including the associated text. Parameters are not required to be used. In some instances, it may be important to know only that a recognition occurred; the application may not process any information any further.

Note also the event's parameters represent one-way communications, that of SAPI to the application. It is not possible to change the parameter information and send the changed parameters back to the engine.