Programming Notes for Visual Basic

Hidden members

Certain methods or properties (collectively called members) are designated as hidden. This indicates that member does not display in a browser such as Visual Basic's IntelliSense (or automatic statement completion) menu or in the Object Browser list. Members may be designated as hidden for several reasons. Most commonly, it represents an advanced feature or capability that is not needed in normal situations. Hidden members should be considered carefully before using them.

To view hidden members

1. On the View menu, click Object Browser.
2. Right-click the Object Browser window, and then click Show Hidden Members. Drag the scroll box to view hidden members that appear in gray text. With Show Hidden Members selected, these will appear in the IntelliSense menu as well.
3. Right-click the Object Browser window, and then select Show Hidden Members again to hide the members.

Determining SAPI's presence

SAPI requires no special error handling outside of Visual Basic's standard procedures. That is, SAPI errors may be trapped and handled using the same techniques presented by Visual Basic.

However, there are two special considerations when working with SAPI. First, the computer on which the application is being developed must have the SAPI library loaded. See Using the Code Examples for details on setting up a Visual Basic environment for SAPI. Second, the computer running the application with SAPI automation must have SAPI 5.1 or later installed.

It is possible to run applications that include SAPI automation without SAPI 5.1. If this is the case, surround the SAPI code with conditional statements to ensure that no SAPI commands are actually executed.

The easiest way to determine if an appropriate version of SAPI is present on a computer is to simply make calls to SAPI and see if they fail. Use error trapping to catch and work around failed SAPI calls. If all the SAPI calls are caught, it is possible to run SAPI-enabled applications on computers without a compatible version of SAPI. Although, those applications cannot use SAPI functions or functionality, but a separate version of the application does not have to be created or maintained.

For instance, if the following code snippet is executed and SAPI 5.1 is not installed, a run-time error results.

Private Sub Form_Load()
    Set RC = New SpSharedRecoContext

    Set myGrammar = RC.CreateGrammar
    myGrammar.DictationSetState SGDSActive
End Sub

The error would be related to creating an object from nonexistent source. On a computer with no version of SAPI loaded, this would commonly display

Run-time error '459':
Object or class does not support the set of events

Therefore, the SAPI calls need an error handler for them. For example, the same code above could be trapped by the following version. The code intends to use gSAPIPresent as a flag marking SAPI's presence. If all the SAPI-related calls are conditional based on gSAPIPresent, the application could run on computers lacking SAPI support. Although those applications could run, voice features could not be used.

Private Sub Form_Load()
    On Error GoTo SAPINotFound
    
    Set RC = New SpSharedRecoContext
    
    Set myGrammar = RC.CreateGrammar
    myGrammar.DictationSetState SGDSActive
    gSAPIPresent = True
    Exit Sub
    
SAPINotFound:
    If Err.Number = 459 Then
        MsgBox "SAPI not found"
    Else
        MsgBox "Error encountered : " & Err.Number
    End If
    
    gSAPIPresent = False
End Sub

If an application needs to explicitly test for the presence of a compatible version of SAPI, use the following code to load a small SAPI object. If the call fails, SAPI is not present.

Private Sub Form_Load()
{
   'Use Visual Basic's built in error checking
   On Error GoTo Err_SAPILoad
	
   Dim PIB As ISpeechPhraseInfoBuilder
   'Now if this call fails Visual Basic's Error handling will kick in and send the program flow to Err_SAPILoad
   Set PIB = New SpPhraseInfoBuilder

Err_SAPILoad:
   MsgBox "Error loading SAPI objects! Please make sure SAPI5.1 is correctly installed.", vbCritical
}

Error Codes

SAPI error codes are listed in Error Codes.

COM Reliance

SAPI automation is built on a COM foundation. As a result many of the SAPI automation calls are virtually identical to correspondingly named calls the C/C++ section of the SAPI documentation. It may be helpful read the related sections for additional insight and suggestions for automation calls. While the C/C++ references will specify C-style programming terms and code samples, in many cases the principles will be the same.