ch15.htm

MAPI__SAPI__TAPI

<p align="center"><b>Table 15.7. The properties and methods of the OLE <tt><font
FACE="Courier">Voice Menu</font></tt> object.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Property/Method</i></td>
    <td WIDTH="188"><i>Parameters</i> </td>
    <td WIDTH="246"><i>Description</i></td>
  </tr>
  <tr>
    <td WIDTH="157"><tt><font FACE="Courier">hWndMenu</font></tt> property </td>
    <td WIDTH="188"><tt><font FACE="Courier">hWnd</font></tt> as long </td>
    <td WIDTH="246">Sets the window handle for a voice menu. Whenever this window is the 
    foreground window, the voice menu is automatically activated; otherwise, it is 
    deactivated. If this property is set to <tt><font FACE="Courier">NULL</font></tt>, the 
    menu is global. </td>
  </tr>
  <tr>
    <td WIDTH="157"><tt><font FACE="Courier">Active</font></tt> property </td>
    <td WIDTH="188"><tt><font FACE="Courier">TRUE</font></tt>/<tt><font FACE="Courier">FALSE</font></tt> 
    </td>
    <td WIDTH="246">Use this to turn the menu on or off. If this is set to <tt><font
    FACE="Courier">TRUE</font></tt>, the menu is active. The menu must be active before its 
    commands will be recognized by the SR engine. </td>
  </tr>
  <tr>
    <td WIDTH="157"><tt><font FACE="Courier">Add</font></tt> method </td>
    <td WIDTH="188"><tt><font FACE="Courier">id</font></tt> as Long, <br>
    <tt><font FACE="Courier">command</font></tt> as String, <br>
    <tt><font FACE="Courier">category</font></tt> as String,<br>
    <tt><font FACE="Courier">description</font></tt> as String </td>
    <td WIDTH="246">Adds a new menu to the list of recognizable menus. The <tt><font
    FACE="Courier">command </font></tt>parameter contains the actual menu item the SR engine 
    will listen for. The <tt><font FACE="Courier">id</font></tt> parameter will be returned 
    when the SR engine recognizes that the <tt><font FACE="Courier">command</font></tt> has 
    been spoken. The other parameters are optional. </td>
  </tr>
  <tr>
    <td WIDTH="157"><tt><font FACE="Courier">Remove</font></tt> method </td>
    <td WIDTH="188"><tt><font FACE="Courier">id</font></tt> as Long </td>
    <td WIDTH="246">Removes an item from the menu list. The <tt><font FACE="Courier">id</font></tt> 
    parameter is the same value used to create the menu in the <tt><font FACE="Courier">Add</font></tt> 
    method. </td>
  </tr>
  <tr>
    <td WIDTH="157"><tt><font FACE="Courier">ListSet</font></tt> method </td>
    <td WIDTH="188"><tt><font FACE="Courier">Name</font></tt> as String, <br>
    <tt><font FACE="Courier">Elements</font></tt> as Long,<br>
    <tt><font FACE="Courier">Data</font></tt> as String </td>
    <td WIDTH="246">Add a list of possible entries for use with a command (see &quot;Using 
    Command Lists with the <tt><font FACE="Courier">Voice Menu</font></tt> Object&quot; later 
    in this chapter). <tt><font FACE="Courier">Name</font></tt> is the name of the list 
    referred to in a command. <tt><font FACE="Courier">Elements</font></tt><i> </i>is the 
    total number of elements in this list. <tt><font FACE="Courier">Data</font></tt> is the 
    set of elements, separated by a <tt><font FACE="Courier">chr(0)</font></tt>. </td>
  </tr>
</table>
</center></div>

<h4>Using Command Lists with the <tt><font FACE="Courier">Voice Menu</font></tt> Object</h4>

<p>The <tt><font FACE="Courier">Voice Menu</font></tt> object allows you to define a 
command that refers to a list. You can then load this list into the grammar using the <tt><font
FACE="Courier">ListSet</font></tt> method. For example, you can use the <tt><font
FACE="Courier">Add</font></tt> method to create a command to send e-mail messages. Then 
you can use the <tt><font FACE="Courier">ListSet</font></tt> method to create a list of 
people to receive e-mail (see Listing 15.2). </p>

<hr>

<blockquote>
  <b><p>Listing 15.2. Using the <tt><font FACE="Courier">Add</font></tt> and <tt><font
  FACE="Courier">ListSet</font></tt> methods of the <tt><font FACE="Courier">Voice Menu</font></tt> 
  object.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Dim Names<br>
  Dim szNULL as String<br>
  szNULL = Chr(0)<br>
  &nbsp;<br>
  &nbsp;<br>
  Call vMenu.Add(109, &quot;Send email to &lt;Names&gt;&quot;)<br>
  Names = &quot;Larry&quot; &amp; szNULL &amp; &quot;Mike&quot; &amp; szNULL &amp; 
  &quot;Gib&quot; &amp; szNULL &amp; &quot;Doug&quot; &amp; szNULL &amp; <font
  FACE="ZAPFDINGBATS">&Acirc;</font>&quot;George&quot; &amp; szNull<br>
  Call Vmenu.ListSet(&quot;Names&quot;, 5, Names)</font></tt> </p>
</blockquote>

<hr>

<h3><a NAME="OLEAutomationTexttoSpeechServices">OLE Automation Text-to-Speech Services</a></h3>

<p>You can gain access to the OLE Automation TTS services using only one object-the <tt><font
FACE="Courier">Voice Text</font></tt> object. The <tt><font FACE="Courier">Voice Text</font></tt> 
object has four properties and seven methods. Table 15.8 shows the properties and methods, 
along with their parameters and short descriptions. <br>
</p>

<p align="center"><b>Table 15.8. The properties and methods of the <tt><font
FACE="Courier">Voice Text</font></tt> object.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Property/Method</i></td>
    <td WIDTH="151"><i>Parameters</i> </td>
    <td WIDTH="250"><i>Description</i></td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">Register</font></tt> method </td>
    <td WIDTH="151"><tt><font FACE="Courier">AppName</font></tt> as string </td>
    <td WIDTH="250">Used to register the application with the TTS engine. This must be called 
    before any other methods are called. </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">Callback</font></tt> property </td>
    <td WIDTH="151"><tt><font FACE="Courier">Project.Class</font></tt> as string </td>
    <td WIDTH="250">This property is used to establish a callback interface between the <tt><font
    FACE="Courier">Voice Text</font></tt> object and your program. See the &quot;Using the 
    Voice Text Callback&quot; section later in this chapter. </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">Enabled</font></tt> property </td>
    <td WIDTH="151"><tt><font FACE="Courier">TRUE</font></tt>/<tt><font FACE="Courier">FALSE</font></tt> 
    </td>
    <td WIDTH="250">Use this property to turn the TTS service on or off. This must be set to <tt><font
    FACE="Courier">TRUE</font></tt> for the <tt><font FACE="Courier">Voice Text</font></tt> 
    object to speak text. </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">Speed</font></tt> property </td>
    <td WIDTH="151"><tt><font FACE="Courier">lSpeed</font></tt> as Long </td>
    <td WIDTH="250">Setting this value controls the speed (in words per minute) at which text 
    is spoken. Setting the value to <tt><font FACE="Courier">0</font></tt> sets the slowest 
    speed. Setting the value to <tt><font FACE="Courier">-1</font></tt> sets the fastest 
    speed. </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">IsSpeaking</font></tt> </td>
    <td WIDTH="151"><tt><font FACE="Courier">TRUE</font></tt>/<tt><font FACE="Courier">FALSE</font></tt> 
    </td>
    <td WIDTH="250">Indicates whether the TTS engine is currently speaking text. You can poll 
    this read-only property to determine when the TTS engine is busy or idle. Note that VB4 
    programmers should use the <tt><font FACE="Courier">Callback</font></tt> property instead 
    of this property. </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">Speak</font></tt> method </td>
    <td WIDTH="151"><tt><font FACE="Courier">cText</font></tt> as string, <br>
    <tt><font FACE="Courier">lFlags</font></tt> as Long </td>
    <td WIDTH="250">Use this method to get the TTS engine to speak text. The <tt><font
    FACE="Courier">lFlags</font></tt> parameter can contain a value to indicate this is a 
    statement, question, and so on. </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">StopSpeaking</font></tt> method </td>
    <td WIDTH="151">(none)</td>
    <td WIDTH="250">Use this method to force the TTS engine to stop speaking the current text. 
    </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">AudioPause</font></tt> </td>
    <td WIDTH="151">(none)</td>
    <td WIDTH="250">Use this method to pause all TTS activity. This affects all applications 
    using TTS services at this site (pc). </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">AudioResume</font></tt> </td>
    <td WIDTH="151">(none)</td>
    <td WIDTH="250">Use this method to resume TTS activity after calling <tt><font
    FACE="Courier">AudioPause</font></tt>. This affects all applications using TTS services at 
    this site (pc). </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">AudioRewind</font></tt> </td>
    <td WIDTH="151">(none)</td>
    <td WIDTH="250">Use this method to back up the TTS playback approximately one phrase or 
    sentence. </td>
  </tr>
  <tr>
    <td WIDTH="189"><tt><font FACE="Courier">AudioFastForward</font></tt> </td>
    <td WIDTH="151">(none)</td>
    <td WIDTH="250">Use this method to advance the TTS engine approximately one phrase or 
    sentence. </td>
  </tr>
</table>
</center></div>

<h4>Using the Voice Text Callback</h4>

<p>The Voice Text type library provides a unique and very efficient method for registering 
callbacks using a Visual Basic 4.0 class module. In order to establish an automatic 
notification from the TTS engine, all you need to do is add a VB4 class module to your 
application. This class module must have two functions created: 

<ul>
  <li><tt><font FACE="Courier">SpeakingStarted</font></tt>-This event is fired each time the 
    TTS engine begins speaking text. </li>
  <li><tt><font FACE="Courier">SpeakingDone</font></tt>-This event is fired each time the TTS 
    engine stops speaking text. </li>
</ul>

<hr>

<blockquote>
  <b><p>Listing 15.3. Creating the notification routines for a <tt><font FACE="Courier">Voice 
  Text</font></tt> object.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Function SpeakingDone()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;VtintrForm.StatusMsg.Text = &quot;Speaking Done notification&quot; 
  &amp; Chr(13) &amp; Chr(10) &amp; <font FACE="ZAPFDINGBATS">&Acirc;</font>VtintrForm.StatusMsg.Text 
  <br>
  End Function<br>
  <br>
  Function SpeakingStarted()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;VtintrForm.StatusMsg.Text = &quot;Speaking Started 
  notification&quot; &amp; Chr(13) &amp; Chr(10) <font FACE="ZAPFDINGBATS">&Acirc;</font>&amp; 
  VtintrForm.StatusMsg.Text<br>
  End Function</font></tt> </p>
</blockquote>

<hr>

<p>Only VB4 applications can use this method of establishing callbacks through class 
modules. If you are using the TTS objects with other VBA-compatible languages, you need to 
set up a routine, using a timer, that will regularly poll the <tt><font FACE="Courier">IsSpeaking</font></tt> 
property. The <tt><font FACE="Courier">IsSpeaking</font></tt> property is set to <tt><font
FACE="Courier">TRUE</font></tt> while the TTS engine is speaking text. </p>

<h2><a NAME="Summary"><font SIZE="5" COLOR="#FF0000">Summary</font></a> </h2>

<p>In this chapter you learned the details of the SR and TTS interfaces defined by the 
Microsoft SAPI model. You learned that the SAPI model is based on the Component Object 
Model (COM) interface and that Microsoft has defined two distinct levels of SAPI services: 

<ul>
  <li><i>High-level SAPI</i>-This provides a command-and-control level of service. This is 
    good for detecting menu and system-level commands and for speaking simple text. </li>
  <li><i>Low-level SAPI</i>-This provides a much more flexible interface and allows 
    programmers access to extended SR and TTS services. </li>
</ul>

<p>You learned that the two levels of SAPI service each contain several COM interfaces 
that allow C programmers access to speech services. These interfaces include the ability 
to set and get engine attributes, turn the services on or off, display dialog boxes for 
user interaction, and perform direct TTS and SR functions. </p>

<p>Since the SAPI model is based on the COM interface, high-level languages such as Visual 
Basic cannot directly call functions using the standard API calls. Instead, Microsoft has 
developed OLE Automation type libraries for use with Visual Basic and other VBA-compliant 
systems. The two type libraries are: 

<ul>
  <li><i>Voice Command Objects</i>-This provides access to speech recognition services. </li>
  <li><i>Voice Text Objects</i>-This provides access to text-to-speech services. </li>
</ul>

<p>You now have a good understanding of the types of speech recognition and text-to-speech 
services that are available with the Microsoft SAPI model. In the next chapter, you'll 
learn about details surrounding the design and implementation of SAPI applications, 
including typical hardware required, technology limits, and design considerations when 
building SAPI applications. </p>

<hr WIDTH="100%">

<p align="center"><a HREF="ch14.htm"><img SRC="pc.gif" BORDER="0" HEIGHT="88" WIDTH="140"></a><a
HREF="#CONTENTS"><img SRC="cc.gif" BORDER="0" HEIGHT="88" WIDTH="140"></a><a
HREF="index.htm"><img SRC="hb.gif" BORDER="0" HEIGHT="88" WIDTH="140"></a> <a
HREF="ch16.htm"><img SRC="nc.gif" BORDER="0" HEIGHT="88" WIDTH="140"></a></p>

<hr WIDTH="100%">
<layer src="http://www.spidersoft.com/ads/bwz468_60.htm" visibility="hidden" id="a1" width="600" onload="moveToAbsolute(ad1.pageX,ad1.pageY); a1.clip.height=60;visibility='show';">
</layer>
</body>
</html>