www.pudn.com > cspeech.zip > classes.tex

\chapter{Class reference}\label{classes} 
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% 
\setfooter{\thepage}{}{}{}{}{\thepage} 
 
\section{\class{CSpeech}}\label{cspeech} 
 
CSpeech is used to control SAPI and also to receive feedback. If you wish to receive feedback, 
derive a new class and override one or more On... functions. 
 
Note that the MFC-conformant types CString and BOOL are used. If you are using wxWindows, 
these are actually wxString and Bool. 
 
\wxheading{Member functions} 
 
\membersection{CSpeech::CSpeech}\label{cspeechconstr} 
 
\func{}{CSpeech}{\void} 
 
Constructs a new speech object. Call \helpref{CSpeech::Init}{cspeechinit} to initialize 
the object and \helpref{CSpeech::Terminate}{cspeechterminate} to terminate the object. 
 
\membersection{CSpeech::\destruct{CSpeech}} 
 
\func{}{\destruct{CSpeech}}{\void} 
 
Destructor. 
 
\membersection{CSpeech::AboutDialog}\label{cspeechaboutdialog} 
 
\func{BOOL}{AboutDialog}{\param{window\_t }{parentWindow}, \param{const CString\& }{title = ""}} 
 
Invokes the 'About' dialog for the current engine. 
 
{\it parentWindow} is an HWND in the current implementation. 
 
{\it title} is the title that should appear in the dialog. Current this is not used, 
and the engine supplies the title. 
 
Returns FALSE if the engine does not implement it, or there was some other problem. 
 
\membersection{CSpeech::Default}\label{cspeechdefault} 
 
\func{BOOL}{Default}{\void} 
 
Sets the text-to-speech engine to its defaults by innjecting a RST tag. 
 
\membersection{CSpeech::Enumerate}\label{cspeechenumerate} 
 
\func{BOOL}{EnumerateModes}{\void} 
 
Enumerates all the possible modes (voices). This is called by \helpref{CSpeech::Init}{cspeechinit} but 
may be called again if, for example, the user has installed or removed engines. 
 
\membersection{CSpeech::FindMode}\label{cspeechfindmode} 
 
\func{int}{FindMode}{\param{const CString\& }{modeName}} 
 
Finds the index of the mode matching the given name. 
 
The return value will be between zero and the number returned 
by \helpref{CSpeech::GetModeCount}{cspeechgetmodecount}; or it will 
be -1 to indicate that the mode was not found. 
 
\membersection{CSpeech::GeneralDialog}\label{cspeechgeneraldialog} 
 
\func{BOOL}{GeneralDialog}{\param{window\_t }{parentWindow}, \param{const CString\& }{title = ""}} 
 
Invokes the general settings dialog for the current engine. 
 
{\it parentWindow} is an HWND in the current implementation. 
 
{\it title} is the title that should appear in the dialog. Current this is not used, 
and the engine supplies the title. 
 
Returns FALSE if the engine does not implement it, or there was some other problem. 
 
\membersection{CSpeech::GetMaxPitch}\label{cspeechgetmaxpitch} 
 
\constfunc{int}{GetMaxPitch}{\void} 
 
Returns the maximum pitch value. 
 
\membersection{CSpeech::GetMaxSpeed}\label{cspeechgetmaxspeed} 
 
\constfunc{int}{GetMaxSpeed}{\void} 
 
Returns the maximum speed value. 
 
\membersection{CSpeech::GetMaxVolume}\label{cspeechgetmaxvolume} 
 
\constfunc{int}{GetMaxVolume}{\void} 
 
Returns the maximum volume value. 
 
\membersection{CSpeech::GetMinPitch}\label{cspeechgetminpitch} 
 
\constfunc{int}{GetMinPitch}{\void} 
 
Returns the minimum pitch value. 
 
\membersection{CSpeech::GetMinSpeed}\label{cspeechgetminspeed} 
 
\constfunc{int}{GetMinSpeed}{\void} 
 
Returns the minimum speed value. 
 
\membersection{CSpeech::GetMinVolume}\label{cspeechgetminvolume} 
 
\constfunc{int}{GetMinVolume}{\void} 
 
Returns the minimum volume value. 
 
\membersection{CSpeech::GetModeCount}\label{cspeechgetmodecount} 
 
\constfunc{int}{GetModeCount}{\void} 
 
Returns the number of modes (voices) currently supported. 
 
\membersection{CSpeech::GetModeFeatures}\label{cspeechgetmodefeatures} 
 
\constfunc{long}{GetModeFeatures}{\param{int}{ mode}} 
 
Returns a bitlist of the features supported by this mode (voice) at index {\it mode}. 
 
{\it mode} can be between zero and the number returned 
by \helpref{CSpeech::GetModeCount}{cspeechgetmodecount}. 
 
The return value types will eventually be replaced by values independent of 
the SAPI header file. 
 
\membersection{CSpeech::GetModeName}\label{cspeechgetmodename} 
 
\constfunc{CString}{GetModeName}{\param{int}{ mode}} 
 
Returns the name of the mode (voice) at index {\it mode}. 
 
{\it mode} can be between zero and the number returned 
by \helpref{CSpeech::GetModeCount}{cspeechgetmodecount}. 
 
\membersection{CSpeech::Init}\label{cspeechinit} 
 
\func{BOOL}{Init}{\void} 
 
Initializes and enumerates modes. You must call this function 
before calling other member functions. 
 
See also \helpref{CSpeech::Terminate}{cspeechterminate}. 
 
\membersection{CSpeech::Inject}\label{cspeechinject} 
 
\func{BOOL}{Inject}{\param{const CString\& }{text}} 
 
Injects text-to-speech control tags into the text currently being spoken. 
A string can contain multiple tags, separated by spaces. 
 
Returns TRUE if successful, FALSE otherwise. 
 
\membersection{CSpeech::LexiconDialog}\label{cspeechlexicondialog} 
 
\func{BOOL}{LexiconDialog}{\param{window\_t }{parentWindow}, \param{const CString\& }{title = ""}} 
 
Invokes the lexicon dialog for the current engine. 
 
{\it parentWindow} is an HWND in the current implementation. 
 
{\it title} is the title that should appear in the dialog. Current this is not used, 
and the engine supplies the title. 
 
Returns FALSE if the engine does not implement it, or there was some other problem. 
 
\membersection{CSpeech::OnAttribChanged}\label{cspeechonattribchanged} 
 
\func{virtual BOOL}{OnAttributeChanged}{\param{long}{ attribId}} 
 
Called when an attribute has changed. 
 
\membersection{CSpeech::OnAudioStart}\label{cspeechonaudiostart} 
 
\func{virtual BOOL}{OnAudioStart}{\param{timestamp\_t}{ timeStamp}} 
 
Called when audio output starts. 
 
\membersection{CSpeech::OnAudioStop}\label{cspeechonaudiostop} 
 
\func{virtual BOOL}{OnAudioStop}{\param{timestamp\_t}{ timeStamp}} 
 
Called when audio output stops. 
 
\membersection{CSpeech::OnBookMark}\label{cspeechonbookmark} 
 
\func{virtual BOOL}{OnBookMark}{\param{timestamp\_t}{ timeStamp}, \param{long}{ markNum}} 
 
Called when a bookmark is encountered. 
 
\membersection{CSpeech::OnTextDataDone}\label{cspeechontextdatadone} 
 
\func{virtual BOOL}{OnTextDataStarted}{\param{timestamp\_t}{ timeStamp}, \param{long}{ flags}} 
 
Called when utterance of the text data has completed. 
 
Note: this doesn't seem to be called by SAPI. Use \helpref{CSpeech::OnAudioStop}{cspeechonaudiostop} instead. 
 
\membersection{CSpeech::OnTextDataStarted}\label{cspeechontextdatastarted} 
 
\func{virtual BOOL}{OnTextDataStarted}{\param{timestamp\_t}{ timeStamp}} 
 
Called when the text data has been sent to the engine. 
 
Note: this doesn't seem to be called by SAPI. Use \helpref{CSpeech::OnAudioStart}{cspeechonaudiostart} instead. 
 
\membersection{CSpeech::OnVisual}\label{cspeechonvisual} 
 
\func{virtual BOOL}{OnVisual}{\param{timestamp\_t}{ timeStamp}, \param{char}{ IPAPhoneme},\rtfsp 
\param{char}{ enginePhoneme}, \param{long}{ hints}, \param{const CSpeechMouth\&}{ mouth}} 
 
Called to give the application the chance to draw a visual representation of the current utterance. 
 
\membersection{CSpeech::OnWordPosition}\label{cspeechonwordposition} 
 
\func{virtual BOOL}{OnWordPosition}{\param{timestamp\_t}{ timeStamp}, \param{long}{ byteOffset}} 
 
Notifies the application of the word that is currently being played. 
 
\membersection{CSpeech::Pause}\label{cspeechpause} 
 
\func{BOOL}{Pause}{\param{BOOL}{ pause}} 
 
If {\it pause} is TRUE, the speech will be paused. If {\it pause} is FALSE, the speech 
is resumed. 
 
Returns TRUE if successful, FALSE otherwise. 
 
\membersection{CSpeech::Reset}\label{cspeechreset} 
 
\func{BOOL}{Reset}{\void} 
 
Resets the text-to-speech engine. 
 
\membersection{CSpeech::Say}\label{cspeechsay} 
 
\func{BOOL}{Say}{\param{const CString\& }{text}, \param{BOOL }{tagged = FALSE}} 
 
Utters the given text. If {\it tagged} is TRUE, the text is treated as tagged (there are 
SAPI tags inserted for controlling emphasis etc.) 
 
Returns TRUE if successful, FALSE otherwise. 
 
\membersection{CSpeech::SetMode}\label{cspeechsetmode} 
 
\func{BOOL}{SetMode}{\param{int}{ mode}} 
 
Sets the current mode (voice). 
 
{\it mode} can be between zero and the number returned 
by \helpref{CSpeech::GetModeCount}{cspeechgetmodecount}. 
 
\membersection{CSpeech::SetPitch}\label{cspeechsetpitch} 
 
\func{BOOL}{SetPitch}{\param{int}{ pitch}} 
 
Sets the pitch. {\it pitch} should be a value between 
the values returned by \helpref{CSpeech::GetMinPitch}{cspeechgetminpitch} and 
\rtfsp\helpref{CSpeech::GetMaxPitch}{cspeechgetmaxpitch}. 
 
\membersection{CSpeech::SetSpeed}\label{cspeechsetspeed} 
 
\func{BOOL}{SetSpeed}{\param{long}{ speed}} 
 
Sets the speed. {\it speed} should be a value between 
the values returned by \helpref{CSpeech::GetMinSpeed}{cspeechgetminspeed} and 
\rtfsp\helpref{CSpeech::GetMaxSpeed}{cspeechgetmaxspeed}. 
 
\membersection{CSpeech::SetVolume}\label{cspeechsetvolume} 
 
\func{BOOL}{SetVolume}{\param{long}{ volume}} 
 
Sets the volume. {\it volume} should be a value between 
the values returned by \helpref{CSpeech::GetMinVolume}{cspeechgetminvolume} and 
\rtfsp\helpref{CSpeech::GetMaxVolume}{cspeechgetmaxvolume}. 
 
\membersection{CSpeech::Terminate}\label{cspeechterminate} 
 
\func{BOOL}{Terminate}{\void} 
 
Cleans up the CSpeech object and associated COM objects. You must call this function 
before the speech object is destroyed. 
 
See also \helpref{CSpeech::Init}{cspeechinit}. 
 
\membersection{CSpeech::TranslateDialog}\label{cspeechtranslatedialog} 
 
\func{BOOL}{TranslateDialog}{\param{window\_t }{parentWindow}, \param{const CString\& }{title = ""}} 
 
Invokes the translation dialog for the current engine, letting the user control symbols, currencies, 
abbreviations, and number-translation techniques. 
 
{\it parentWindow} is an HWND in the current implementation. 
 
{\it title} is the title that should appear in the dialog. Current this is not used, 
and the engine supplies the title. 
 
Returns FALSE if the engine does not implement it, or there was some other problem. 
 
\section{\class{CSpeechMouth}}\label{cspeechmouth} 
 
CSpeechMouth is a class holding information about the mouth position, and is currently only 
used in \helpref{CSpeech::OnVisual}{cspeechonvisual}. 
 
This class will be documented in more detail at a future date. 
 
\wxheading{Data members} 
 
\membersection{CSpeechMouth::m\_mouthHeight}\label{cspeechmouthmouthheight} 
 
\member{int}{m\_mouthHeight} 
 
Mouth height. 
 
\membersection{CSpeechMouth::m\_mouthWidth}\label{cspeechmouthmouthwidth} 
 
\member{int}{m\_mouthWidth} 
 
Mouth width. 
 
\membersection{CSpeechMouth::m\_mouthUpturn}\label{cspeechmouthmouthupturn} 
 
\member{int}{m\_mouthUpturn} 
 
Mouth upturn. 
 
\membersection{CSpeechMouth::m\_jawOpen}\label{cspeechmouthjawopen} 
 
\member{int}{m\_jawOpen} 
 
Extent of the jaw. 
 
\membersection{CSpeechMouth::m\_teethUpperVisible}\label{cspeechmouthteethuppervisible} 
 
\member{int}{m\_teethUpperVisible} 
 
Extent to which the upper teeth are visible. 
 
\membersection{CSpeechMouth::m\_teethLowerVisible}\label{cspeechmouthteethlowervisible} 
 
\member{int}{m\_teethLowerVisible} 
 
Extent to which the lower teeth are visible. 
 
\membersection{CSpeechMouth::m\_tonguePosn}\label{cspeechmouthtongueposn} 
 
\member{int}{m\_tonguePosn} 
 
Tongue position. 
 
\membersection{CSpeechMouth::m\_lipTension}\label{cspeechmouthliptension} 
 
\member{int}{m\_lipTension} 
 
Lip tension. 
 
\section{Data types}\label{datatypes} 
 
The following data types have been defined for CSpeech. 
 
\wxheading{timestamp_t} 
 
This is defined as u_int64_t. 
 
\wxheading{window_t} 
 
This is defined as void*, and is converted to a HWND in the CSpeech implementation.