Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 1286 insertions, 0 deletions

diff --git a/interfaces/kspeech/kspeech.h b/interfaces/kspeech/kspeech.h
new file mode 100644
index 000000000..b97314760
--- /dev/null
+++ b/interfaces/kspeech/kspeech.h
@@ -0,0 +1,1286 @@
+/***************************************************** vim:set ts=4 sw=4 sts=4:
+  kspeech.h
+  KTTSD DCOP Interface
+  --------------------
+  Copyright:
+  (C) 2002-2003 by José Pablo Ezequiel "Pupeno" Fernández <pupeno@kde.org>
+  (C) 2003-2004 by Olaf Schmidt <ojschmidt@kde.org>
+  (C) 2004-2005 by Gary Cramblitt <garycramblitt@comcast.net>
+  -------------------
+  Original author: José Pablo Ezequiel "Pupeno" Fernández
+ ******************************************************************************/
+
+/***************************************************************************
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; version 2 of the License.               *
+ *                                                                         *
+ ***************************************************************************/
+
+#ifndef _KSPEECH_H_
+#define _KSPEECH_H_
+
+#include <dcopobject.h>
+#include <qstringlist.h>
+
+/**
+ * @interface KSpeech
+ *
+ * kspeech - the KDE Text-to-Speech API.
+ *
+ * @version 1.0 Draft 10
+ *
+ * @since KDE 3.4
+ *
+ * This class defines the DCOP interface for applications desiring to speak text.
+ * Applications may speak text by sending DCOP messages to application "kttsd" object "KSpeech".
+ *
+ * %KTTSD -- the KDE Text-to-Speech Deamon -- is the program that supplies the services
+ * in the KDE Text-to-Speech API.
+ *
+ * @warning The KSpeech interface is still being developed and is likely to change in the future.
+ *
+ * @section Features
+ *
+ *   - Priority system for Screen Readers, warnings and messages, while still playing
+ *     regular texts.
+ *   - Long text is parsed into sentences.  User may backup by sentence or part,
+ *     replay, pause, and stop playing.
+ *   - Handles multiple speaking applications.  Text messages are treated like print jobs.
+ *     Jobs may be created, started, stopped, paused, resumed, and deleted.
+ *   - Speak contents of clipboard.
+ *   - Speak KDE notifications.
+ *   - Plugin-based text job filtering permits substitution for misspoken words,
+ *     abbreviations, etc., transformation of XML or XHTML to SSML, and automatic
+ *     choice of appropriate synthesis engine.
+ *
+ * @section Requirements
+ *
+ * You may build any KDE application to use KSpeech, since the interface is in kdelibs, but
+ * the kdeaccessibility package must be installed for KTTS to function.
+ *
+ * You will need a speech synthesis engine, such as Festival.  See the KTTS Handbook
+ * for the latest information on installing and configuring speech engines and voices
+ * with KTTS.
+ *
+ * @section goals Design Goals
+ *
+ * The KDE Text-to-Speech API is designed with the following goals:
+ *
+ *   - Support the features enumerated above.
+ *   - Plugin-based architecture for support of a wide variety of speech synthesis
+ *     engines and drivers.
+ *   - Permit generation of speech from the command line (or via shell scripts)
+ *     using the KDE DCOP utilities.
+ *   - Provide a lightweight and easily usable interface for applications to
+ *     generate speech output.
+ *   - Applications need not be concerned about contention over the speech device.
+ *   - Provide limited support for speech markup languages, such as Sable,
+ *     Java %Speech Markup Language (JSML), and %Speech Markup Meta-language (SMML).
+ *   - Provide limited support for embedded speech markers.
+ *   - Asynchronous to prevent system blocking.
+ *   - Plugin-based audio architecture.  Currently supports aRts but will support
+ *     additional audio engines in the future, such as gstreamer.
+ *   - Compatible with original %KTTSD API as developed by José Pablo Ezequiel
+ *     "Pupeno" Fernández (avoid breaking existing applications).
+ *
+ * Architecturally, applications interface with %KTTSD, which performs queueing,
+ * speech job managment, plugin management and sentence parsing.  %KTTSD interfaces with a
+ * %KTTSD speech plugin(s), which then interfaces with the speech engine(s) or driver(s).
+ *
+   @verbatim
+         application
+              ^
+              |  via DCOP (the KDE Text-to-Speech API)
+              v
+            kttsd
+              ^
+              |  KTTSD plugin API
+              v
+         kttsd plugin
+              ^
+              |
+              v
+        speech engine
+   @endverbatim
+ *
+ * The %KTTSD Plugin API is documented in PluginConf in the kdeaccessibility module.
+ *
+ * There is a separate GUI application, called kttsmgr, for providing %KTTSD
+ * configuration and job management.
+ *
+ * kttsd maintains 4 types of speech output:
+ *   - Screen Reader Output
+ *   - Warnings
+ *   - Messages
+ *   - Text Jobs
+ *
+ * Method sayScreenReaderOutput speaks Screen Reader output.
+ * It pre-empts any other speech in progress,
+ * including other Screen Reader outputs, i.e., it is not a queue.
+ * This method is reserved for use by Screen Readers.
+ *
+ * Methods sayWarning and sayMessage place messages into the Warnings and
+ * Messages queues respectively.  Warnings take priority over messages, which take priority
+ * over text jobs.  Warnings and messages are spoken when the currently-speaking
+ * sentence of a text job is finished.
+ *
+ * setText places text into the text job queue. startText begins speaking jobs.
+ * When one job finishes, the next job begins.  Method appendText adds
+ * additional parts to a text job.  Within a text job, the application (and user
+ * via the kttsmgr GUI), may back up or advance by sentence or part, or rewind
+ * to the beginning.
+ * See jumpToTextPart and moveRelTextSentence.
+ * Text jobs may be paused, stopped, and resumed or deleted from the queue.
+ * See pauseText, stopText, resumeText, and removeText.
+ *
+ * @section cmdline DCOP Command-line Interface
+ *
+ * To create a text job to be spoken
+ *
+   @verbatim
+     dcop kttsd KSpeech setText <text> <talker>
+   @endverbatim
+ *
+ * where \<text\> is the text to be spoken, and \<talker\> is usually a language code
+ * such as "en", "cy", etc.
+ *
+ * Example.
+ *
+   @verbatim
+     dcop kttsd KSpeech setText "This is a test." "en"
+   @endverbatim
+ *
+ * To start speaking the text.
+ *
+   @verbatim
+     dcop kttsd KSpeech startText 0
+   @endverbatim
+ *
+ * You can combine the setText and startText commands into a single command.
+ *
+   @verbatim
+     dcop kttsd KSpeech sayText <text> <talker>
+   @endverbatim
+ *
+ * @since KDE 3.5
+ *
+ * To stop speaking and rewind to the beginning of the text.
+ *
+   @verbatim
+     dcop kttsd KSpeech stopText 0
+   @endverbatim
+ *
+ * Depending upon the speech plugin used, speaking may not immediately stop.
+ *
+ * To stop and remove a text job.
+ *
+   @verbatim
+     dcop kttsd KSpeech removeText 0
+   @endverbatim
+ *
+ * Note: For more information about talker codes, see talkers below.
+ *
+ * @section programming Calling KTTSD from a Program
+ *
+ * There are two methods of making DCOP calls from your application to %KTTSD.
+ *
+ *   - Manually code them using dcopClient object.  See kdebase/konqueror/kttsplugin/khtmlkttsd.cpp
+ *     for an example.  This method is recommended if you want to make a few simple calls to KTTSD.
+ *   - Use kspeech_stub as described below.  This method generates the marshalling code for you
+ *     and is recommended for a more complex speech-enabled applications.  kcmkttsmgr in the
+ *     kdeaccessibility module is an example that uses this method.
+ *
+ * To make DCOP calls from your program using kspeech_stub, follow these steps:
+ *
+ * 1.  Include kspeech_stub.h in your code.  Derive an object from the KSpeech_stub interface.
+ *     For example, suppose you are developing a KPart and want to call %KTTSD.
+ *     Your class declaration might look like this:
+ *
+   @verbatim
+     #include <kspeech_stub.h>
+     class MyPart: public KParts::ReadOnlyPart, public KSpeech_stub {
+   @endverbatim
+ *
+ * 2.  In your class constructor, initialize DCOPStub, giving it the sender
+ *     "kttsd", object "KSpeech".
+ *
+   @verbatim
+     MyPart::MyPart(QWidget *parent, const char *name) :
+        KParts::ReadOnlyPart(parent, name),
+        DCOPStub("kttsd", "KSpeech") {
+   @endverbatim
+ *
+ * 3.  See if KTTSD is running, and if not, start it.
+ *
+   @verbatim
+     DCOPClient *client = dcopClient();
+     client->attach();
+     if (!client->isApplicationRegistered("kttsd")) {
+         QString error;
+         if (KApplication::startServiceByDesktopName("kttsd", QStringList(), &error))
+             cout << "Starting KTTSD failed with message " << error << endl;
+     }
+   @endverbatim
+ *
+ * If you want to detect if KTTSD is installed without starting it, use this code.
+ *
+   @verbatim
+     KTrader::OfferList offers = KTrader::self()->query("DCOP/Text-to-Speech", "Name == 'KTTSD'");
+     if (offers.count() > 0)
+     {
+       // KTTSD is installed.
+     }
+   @endverbatim
+ *
+ * Typically, you would do this to hide a menu item or button if KTTSD is not installed.
+ *
+ * 4.  Make calls to KTTSD in your code.
+ *
+   @verbatim
+     uint jobNum = setText("Hello World", "en");
+     startText(jobNum);
+   @endverbatim
+ *
+ * 4.  Add kspeech_DIR and kspeech.stub to your Makefile.am.  Example:
+ *
+   @verbatim
+     kspeech_DIR = $(kde_includes)
+     libmypart_la_SOURCES = kspeech.stub
+   @endverbatim
+ *
+ * @section signals Signals Emitted by KTTSD
+ *
+ * %KTTSD emits a number of DCOP signals, which provide information about sentences spoken,
+ * text jobs started, stopped, paused, resumed, finished, or deleted and markers seen.
+ * In general, these signals are broadcast to any application that connects to them.
+ * Applications should check the appId argument to determine whether the signal belongs to
+ * them or not.
+ *
+ * To receive %KTTSD DCOP signals, follow these steps:
+ *
+ * 1.  Include kspeechsink.h in your code.  Derive an object from the KSpeechSink interface
+ *     and declare a method for each signal you'd like to receive.  For example,
+ *     if you were coding a KPart and wanted to receive the KTTSD signal sentenceStarted:
+ *
+   @verbatim
+     #include <kspeechsink.h>
+     class MyPart:
+         public KParts::ReadOnlyPart,
+         virtual public KSpeechSink
+     {
+         protected:
+            ASYNC sentenceStarted(const QCString& appId, const uint jobNum, const uint seq);
+   @endverbatim
+ *
+ *     You can combine sending and receiving in one object.
+ *
+   @verbatim
+     #include <kspeechsink.h>
+     class MyPart:
+         public KParts::ReadOnlyPart,
+         public KSpeech_stub,
+         virtual public KSpeechSink
+     {
+         protected:
+            ASYNC sentenceStarted(const QCString& appId, const uint jobNum, const uint seq);
+   @endverbatim
+ *
+ *     See below for the signals you can declare.
+ *
+ * 2.  In your class constructor, initialize DCOPObject with the name of your DCOP
+ *     receiving object.
+ *
+   @verbatim
+     MyPart::MyPart(QWidget *parent, const char *name) :
+         KParts::ReadOnlyPart(parent, name),
+         DCOPObject("mypart_kspeechsink") {
+   @endverbatim
+ *
+ *     Use any name you like.
+ *
+ * 3.  Where appropriate (usually in your constructor), make sure your DCOPClient
+ *     is registered and connect the %KTTSD DCOP signals to your declared receiving
+ *     methods.
+ *
+   @verbatim
+     // Register DCOP client.
+     DCOPClient *client = kapp->dcopClient();
+     if (!client->isRegistered())
+     {
+         client->attach();
+         client->registerAs(kapp->name());
+     }
+     // Connect KTTSD DCOP signals to our slots.
+     connectDCOPSignal("kttsd", "KSpeech",
+         "sentenceStarted(QCString,uint,uint)",
+         "sentenceStarted(QCString,uint,uint)",
+         false);
+   @endverbatim
+ *
+ *     Notice that the argument signatures differ slightly from the actual declarations.  For
+ *     example
+ *
+   @verbatim
+     ASYNC sentenceStarted(const QCString& appId, const uint jobNum, const uint seq);
+   @endverbatim
+ *
+ *     becomes
+ *
+   @verbatim
+       "sentenceStarted(QCString,uint,uint)",
+   @endverbatim
+ *
+ *     in the connectDCOPSignal call.
+ *
+ * 4.  Write the definition for the received signal.  Be sure to check whether the signal
+ *     is intended for your application.
+ *
+   @verbatim
+     ASYNC MyPart::sentenceStarted(const QCString& appId, const uint jobNum, const uint seq)
+     {
+         // Check appId to determine if this is our signal.
+         if (appId != dcopClient()->appId()) return;
+         // Do something here.
+     }
+   @endverbatim
+ *
+ * 5.  Add kspeechsink_DIR and kspeechsink.skel to your Makefile.am.  Example for an app
+ *     both sending and receiving.
+ *
+   @verbatim
+     kspeech_DIR = $(kde_includes)
+     kspeechsink_DIR = $(kde_includes)
+     libmypart_la_SOURCES = kspeech.stub kspeechsink.skel
+   @endverbatim
+ *
+ * @section talkers Talkers, Talker Codes, and Plugins
+ *
+ * Many of the methods permit you to specify a desired "talker".  This
+ * may be a simple language code, such as "en" for English, "es" for Spanish, etc.
+ * Code as NULL to use the default configured talker.
+ *
+ * Within KTTSMGR, the user has the ability to configure more than one talker for each language,
+ * with different voices, genders, volumes, and talking speeds.
+ *
+ * Talker codes serve two functions:
+ * - They identify configured plugins, and
+ * - They provide a way for applications to specify the desired speaking attributes
+ *   that influence the choice of plugin to speak text.
+ *
+ * A Talker Code consists of a series of XML tags and attributes.
+ * An example of a full Talker Code with all attributes specified is
+ * \code
+ *   <voice lang="en" name="kal" gender="male"/>
+ *   <prosody volume="soft" rate="fast"/>
+ *   <kttsd synthesizer="Festival" />
+ * \endcode
+ *
+ * (The @e voice and @e prosody tags are adapted from the W3C Speech Synthesis
+ * Markup Language (SSML) and Java Speech Markup Language (JSML).
+ * The @e kttsd tag is an extension to the SMML and JSML languages to support
+ * named synthesizers and text encodings.)
+ * %KTTS doesn't really care about the @e voice, @e prosody, and @e kttsd tags.  In fact,
+ * they may be omitted and just the attributes specified.  The example above then
+ * becomes
+ *
+ *   lang="en" name="kal" gender="male" volume="soft" rate="fast"
+ *   synthesizer="Festival"
+ *
+ * The attributes may be specified in any order.
+ *
+ * For clarity, the rest of the discussion
+ * will omit the @e voice, @e prosody, and @e kttsd tags.
+ *
+ * The attributes that make up a talker code are:
+ *
+ * - @e lang.         Language code and optional country code.
+ *                    Examples: en, es, en_US, en_GB. Codes
+ *                    are case in-sensitive and hyphen (-) or underscore (_) may be
+ *                    used to separate the country code from the language code.
+ * - @e synthesizer.  The name of the synthesizer (plugin) used to produce the speech.
+ * - @e gender.       May be either "male", "female", or "neutral".
+ * - @e name.         The name of the voice code.
+ *                    The choice of voice codes is synthesizer-specific.
+ * - @e volume.       May be "loud", "medium", or "quiet".  A synonym for "quiet" is
+ *                    "soft".
+ * - @e rate.         May be "fast", "medium", or "slow".
+ *
+ * Each plugin, once it has been configured by a user in kttsmgr, returns a
+ * fully-specified talker code to identify itself.  If the plugin supports it,
+ * the user may configure another instance of the plugin with a different set
+ * of attributes.  This is the difference between a "plugin" and a "talker".
+ * A talker is a configured instance of a plugin.  Each plugin (if it supports it)
+ * may be configured as multiple talkers.
+ *
+ * When the user configures %KTTSD, she configures one or more talkers and then
+ * places them in preferred order, top to bottom in kttsmgr.  In effect,
+ * she specifies her preferences for each of the talkers.
+ *
+ * When applications specify a talker code, they need not (and typically do not)
+ * give a full specification.  An example of a talker code with only some of the
+ * attributes specified might be
+ *
+ *   lang="en" gender="female"
+ *
+ * If the talker code is not in XML attribute format, it assumed to be a @e lang
+ * attribute.  So the talker code
+ *
+ *   en
+ *
+ * is interpreted as
+ *
+ *   lang="en"
+ *
+ * When a program requests a talker code in calls to setText, appendText,
+ * sayMessage, sayWarning, and sayScreenReaderOutput,
+ * %KTTSD tries to match the requested talker code to the closest matching
+ * configured talker.
+ *
+ * The @e lang attribute has highest priority (attempting to speak English with
+ * a Spanish synthesizer would likely be unintelligible).  So the language
+ * attribute is said to have "priority".
+ * If an application does not specify a language attribute, a default one will be assumed.
+ * The rest of the attributes are said to be "preferred".  If %KTTSD cannot find
+ * a talker with the exact preferred attributes requested, the closest matching
+ * talker will likely still be understandable.
+ *
+ * An application may specify that one or more of the attributes it gives in a talker
+ * code have priority by preceeding each priority attribute with an asterisk.
+ * For example, the following talker code
+ *
+ *  lang="en" gender="*female" volume="soft"
+ *
+ * means that the application wants to use a talker that supports American English language
+ * and Female gender.  If there is more than one such talker, one that supports
+ * Soft volume would be preferred.  Notice that a talker configured as English, Male,
+ * and Soft volume would not be picked as long as an English Female talker is
+ * available.
+ *
+ * The algorithm used by %KTTSD to find a matching talker is as follows:
+ *
+ * - If language code is not specified by the application, assume default configured
+ *   by user.  The primary language code automatically has priority.
+ * - (Note: This is not yet implemented.)
+ *   If there are no talkers configured in the language, %KTTSD will attempt
+ *   to automatically configure one (see automatic configuraton discussion below)
+ * - The talker that matches on the most priority attributes wins.
+ * - If a tie, the one that matches on the most preferred attributes wins.
+ * - If there is still a tie, the one nearest the top of the kttsmgr display
+ *   (first configured) will be chosen.
+ *
+ * Language codes actually consist of two parts, a language code and an optional
+ * country code.  For example, en_GB is English (United Kingdom).  The language code is
+ * treated as a priority attribute, but the country code (if specified) is treated
+ * as preferred.  So for example, if an application requests the following
+ * talker code
+ *
+ *   lang="en_GB" gender="male" volume="medium"
+ *
+ * then a talker configured as lang="en" gender="male" volume="medium" would be
+ * picked over one configured as lang="en_GB" gender="female" volume="soft",
+ * since the former matches on two preferred attributes and the latter only on the
+ * preferred attribute GB. An application can override this and make the country
+ * code priority with an asterisk.  For example,
+ *
+ *   lang="*en_GB" gender="male" volume="medium"
+ *
+ * To specify that American English is priority, put an asterisk in front of
+ * en_US, like this.
+ *
+ *   lang="*en_US" gender="male" volume="medium"
+ *
+ * Here the application is indicating that a talker that speaks American English
+ * has priorty over one that speaks a different form of English.
+ *
+ * (Note: Not yet implemented).
+ * If a language code is specified, and no plugin is currently configured
+ * with a matching language code, %KTTSD will attempt to automatically
+ * load and configure a plugin to support the requested language.  If
+ * there is no such plugin, or there is a plugin but it cannot automatically
+ * configure itself, %KTTSD will pick one of the configured plugins using the
+ * algorithm given above.
+ *
+ * Notice that %KTTSD will always pick a talker, even if it is a terrible match.
+ * (The principle is that something heard is better than nothing at all.  If
+ * it sounds terrible, user will change his configuration.)
+ * If an attribute is absolutely mandatory -- in other words the application
+ * must speak with the attribute or not at all -- the application can determine if
+ * there are any talkers configured with the attribute by calling getTalkers,
+ * and if there are none, display an error message to the user.
+ *
+ * Applications can implement their own talker-matching algorithm by
+ * calling getTalkers, then finding the desired talker from the returned
+ * list.  When the full talker code is passed in, %KKTSD will find an exact
+ * match and use the specified talker.
+ *
+ * If an application requires a configuration that user has not created,
+ * it should display a message to user instructing them to run kttsmgr and
+ * configure the desired talker.  (This must be done interactively because
+ * plugins often need user assistance locating voice files, etc.)
+ *
+ * The above scheme is designed to balance the needs
+ * of applications against user preferences.  Applications are given the control
+ * they @e might need, without unnecessarily burdening the application author.
+ * If you are an application author, the above discussion might seem overly
+ * complicated.  It isn't really all that complicated.  Here are rules of thumb:
+ *
+ *   - It is legitimate to give a NULL (0) talker code, in which case, the user's default
+ *     talker will be used.
+ *   - If you know the language code, give that in the talker code, otherwise
+ *     leave it out.
+ *   - If there is an attribute your application @e requires for proper functioning,
+ *     specify that with an asterisk in front of it.  For example, your app might
+ *     speak in two different voices, Male and Female.  (Since your
+ *     app requires both genders, call getTalkers to determine if both genders
+ *     are available, and if not, advise user to configure them.  Better yet,
+ *     give the user a choice of available distinquishing attributes
+ *     (loud/soft, fast/slow, etc.)
+ *   - If there are other attributes you would prefer, specify those without an
+ *     asterisk, but leave them out if it doesn't really make any difference
+ *     to proper functioning of your application.  Let the user decide them
+ *     when they configure %KTTS.
+ *
+ * One final note about talkers.  %KTTSD does talker matching for each sentence
+ * spoken, just before the sentence is sent to a plugin for synthesis.  Therefore,
+ * the user can change the effective talker in mid processing of a text job by
+ * changing his preferences, or even deleting or adding new talkers to the configuration.
+ *
+ * @section markup Speech Markup
+ *
+ * Note: %Speech Markup is not yet fully implemented in %KTTSD.
+ *
+ * Each of the five methods for queueing text to be spoken -- sayScreenReaderOutput,
+ * setText, appendText, sayMessage, and sayWarning -- may contain speech markup,
+ * provided that the plugin the user has configured supports that markup.  The markup
+ * languages and plugins currently supported are:
+ *
+ *   - %Speech Synthesis Markup language (SSML): Festival and Hadifix.
+ *
+ * This may change in the future as synthesizers improve.
+ *
+ * Before including markup in the text sent to kttsd, the application should
+ * query whether the currently-configured plugin
+ * supports the markup language by calling supportsMarkup.
+ *
+ * It it does not support the markup, it will be stripped out of the text.
+ *
+ * @section markers Support for Markers
+ *
+ * Note: Markers are not yet implemented in %KTTSD.
+ *
+ * When using a speech markup language, such as Sable, JSML, or SSML, the application may embed
+ * named markers into the text.  If the user's chosen speech plugin supports markers, %KTTSD
+ * will emit DCOP signal markerSeen when the speech engine encounters the marker.
+ * Depending upon the speech engine and plugin, this may occur either when the speech engine
+ * encounters the marker during synthesis from text to speech, or when the speech is actually
+ * spoken on the audio device.  The calling application can call the supportsMarkers
+ * method to determine if the currently configured plugin supports markers or not.
+ *
+ * @section sentenceparsing Sentence Parsing
+ *
+ * Not all speech engines provide robust capabilities for stopping synthesis that is in progress.
+ * To compensate for this, %KTTSD parses text jobs given to it by the setText and
+ * appendText methods into sentences and sends the sentences to the speech
+ * plugin one at a time.  In this way, should the user wish to stop the speech
+ * output, they can do so, and the worst that will happen is that the last sentence
+ * will be completed.  This is called Sentence Boundary Detection (SBD).
+ *
+ * Sentence Boundary Detection also permits the user to rewind by sentences.
+ *
+ * The default sentence delimiter used for plain text is as follows:
+ *
+ *   - A period (.), question mark (?), exclamation mark (!), colon (:), or
+ *     semi-colon (;) followed by whitespace (including newline), or
+ *   - Two newlines in a row separated by optional whitespace, or
+ *   - The end of the text.
+ *
+ * When given text containing speech markup, %KTTSD automatically determines the markup type
+ * and parses based on the sentence semantics of the markup language.
+ *
+ * An application may change the sentence delimiter by calling setSentenceDelimiter
+ * prior to calling setText.  Changing the delimiter does not affect other
+ * applications.
+ *
+ * Text given to %KTTSD via the sayWarning, sayMessage, and sayScreenReaderOutput
+ * methods is @e not parsed into sentences.  For this reason, applications
+ * should @e not send long messages with these methods.
+ *
+ * Sentence Boundary Detection is implemented as a plugin SBD filter.  See
+ * filters for more information.
+ *
+ * @section filters Filters
+ *
+ * Users may specify filters in the kttsmgr GUI.  Filters are plugins that modify the text
+ * to be spoken or change other characteristics of jobs.  Currently, the following filter plugins
+ * are available:
+ *
+ *   - String Replacer.  Permits users to substitute for mispoken words, or vocalize chat
+ *     emoticons.
+ *   - XML Transformer.  Given a particular XML or XHTML format, permits conversion of the
+ *     XML to SSML (Speech Synthesis Markup Language) using XSLT (XML Style Language - Transforms)
+ *     stylesheets.
+ *   - Talker Chooser.  Permits users to redirect jobs from one configured Talker to another
+ *     based on the contents of the job or application that sent it.
+ *
+ * Additional plugins may be available in the future.
+ *
+ * In additional to these regular filters, KTTS also implements Sentence Boundary Detection (SBD)
+ * as a plugin filter.  See sentenceparsing for more information.
+ *
+ * Regular filters are applied to Warnings, Messages, and Text jobs.  SBD filters are
+ * only applied to regular Text jobs; they are not applied to Warnings and Messages.  Screen
+ * Reader Outputs are never filtered.
+ *
+ * @section authors Authors
+ *
+ * @author José Pablo Ezequiel "Pupeno" Fernández <pupeno@kde.org>
+ * @author Gary Cramblitt <garycramblitt@comcast.net>
+ * @author Olaf Schmidt <ojschmidt@kde.org>
+ * @author Gunnar Schmi Dt <gunnar@schmi-dt.de>
+ */
+
+// NOTE: kspeech class is now obsolete.  Please use KSpeech instead.
+
+class KSpeech : virtual public DCOPObject {
+    K_DCOP
+
+    public:
+        /**
+        * @enum kttsdJobState
+        * Job states returned by method getTextJobState.
+        */
+        enum kttsdJobState
+        {
+            jsQueued = 0,                /**< Job has been queued but is not yet speakable. */
+            jsSpeakable = 1,             /**< Job is speakable, but is not speaking. */
+            jsSpeaking = 2,              /**< Job is currently speaking. */
+            jsPaused = 3,                /**< Job has been paused. */
+            jsFinished = 4               /**< Job is finished and is deleteable. */
+        };
+
+        /**
+        * @enum kttsdMarkupType
+        * %Speech markup language types.
+        */
+        enum kttsdMarkupType
+        {
+            mtPlain = 0,                 /**< Plain text */
+            mtJsml = 1,                  /**< Java %Speech Markup Language */
+            mtSsml = 2,                  /**< %Speech Synthesis Markup Language */
+            mtSable = 3,                 /**< Sable 2.0 */
+            mtHtml = 4                   /**< HTML @since 3.5 */
+        };
+
+    k_dcop:
+        /** @name DCOP Methods */
+        //@{
+
+        /**
+        * Determine whether the currently-configured speech plugin supports a speech markup language.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default talker.
+        * @param markupType     The kttsd code for the desired speech markup language.
+        * @return               True if the plugin currently configured for the indicated
+        *                       talker supports the indicated speech markup language.
+        * @see kttsdMarkupType
+        */
+        virtual bool supportsMarkup(const QString &talker, uint markupType = 0) const = 0;
+
+        /**
+        * Determine whether the currently-configured speech plugin supports markers in speech markup.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default talker.
+        * @return               True if the plugin currently configured for the indicated
+        *                       talker supports markers.
+        */
+        virtual bool supportsMarkers(const QString &talker) const = 0;
+
+        /**
+        * Say a message as soon as possible, interrupting any other speech in progress.
+        * IMPORTANT: This method is reserved for use by Screen Readers and should not be used
+        * by any other applications.
+        * @param msg            The message to be spoken.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default talker.
+        *                       If no plugin has been configured for the specified Talker code,
+        *                       defaults to the closest matching talker.
+        *
+        * If an existing Screen Reader output is in progress, it is stopped and discarded and
+        * replaced with this new message.
+        */
+        virtual ASYNC sayScreenReaderOutput(const QString &msg, const QString &talker) = 0;
+
+        /**
+        * Say a warning.  The warning will be spoken when the current sentence
+        * stops speaking and takes precedence over Messages and regular text.  Warnings should only
+        * be used for high-priority messages requiring immediate user attention, such as
+        * "WARNING. CPU is overheating."
+        * @param warning        The warning to be spoken.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default talker.
+        *                       If no plugin has been configured for the specified Talker code,
+        *                       defaults to the closest matching talker.
+        */
+        virtual ASYNC sayWarning(const QString &warning, const QString &talker) = 0;
+
+        /**
+        * Say a message.  The message will be spoken when the current sentence stops speaking
+        * but after any warnings have been spoken.
+        * Messages should be used for one-shot messages that can't wait for
+        * normal text messages to stop speaking, such as "You have mail.".
+        * @param message        The message to be spoken.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default talker.
+        *                       If no talker has been configured for the specified talker code,
+        *                       defaults to the closest matching talker.
+        */
+        virtual ASYNC sayMessage(const QString &message, const QString &talker) = 0;
+
+        /**
+        * Sets the GREP pattern that will be used as the sentence delimiter.
+        * @param delimiter      A valid GREP pattern.
+        *
+        * The default sentence delimiter is
+          @verbatim
+              ([\\.\\?\\!\\:\\;])(\\s|$|(\\n *\\n))
+          @endverbatim
+        *
+        * Note that backward slashes must be escaped.
+        * When %KTTSD parses the text, it replaces all tabs, spaces, and formfeeds
+        * with a single space, and then replaces the sentence delimiters using
+        * the following statement:
+          @verbatim
+              QString::replace(sentenceDelimiter, "\\1\t");
+          @endverbatim
+        *
+        * which replaces all sentence delimiters with a tab, but
+        * preserving the first capture text (first parenthesis).  In other
+        * words, the sentence punctuation is preserved.
+        * The tab is later used to separate the text into sentences.
+        *
+        * Changing the sentence delimiter does not affect other applications.
+        *
+        * @see sentenceparsing
+        */
+        virtual ASYNC setSentenceDelimiter(const QString &delimiter) = 0;
+
+        /**
+        * Queue a text job.  Does not start speaking the text.
+        * @param text           The message to be spoken.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default plugin.
+        *                       If no plugin has been configured for the specified Talker code,
+        *                       defaults to the closest matching talker.
+        * @return               Job number.
+        *
+        * Plain text is parsed into individual sentences using the current sentence delimiter.
+        * Call setSentenceDelimiter to change the sentence delimiter prior to
+        * calling setText.
+        * Call getTextCount to retrieve the sentence count after calling setText.
+        *
+        * The text may contain speech mark language, such as Sable, JSML, or SSML,
+        * provided that the speech plugin/engine support it.  In this case,
+        * sentence parsing follows the semantics of the markup language.
+        *
+        * Call startText to mark the job as speakable and if the
+        * job is the first speakable job in the queue, speaking will begin.
+        *
+        * @see getTextCount
+        * @see startText
+        */
+        virtual uint setText(const QString &text, const QString &talker) = 0;
+
+        /**
+        * Say a plain text job.  This is a convenience method that
+        * combines setText and startText into a single call.
+        * @param text           The message to be spoken.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default plugin.
+        *                       If no plugin has been configured for the specified Talker code,
+        *                       defaults to the closest matching talker.
+        * @return               Job number.
+        *
+        * Plain text is parsed into individual sentences using the current sentence delimiter.
+        * Call setSentenceDelimiter to change the sentence delimiter prior to
+        * calling setText.
+        * Call getTextCount to retrieve the sentence count after calling setText.
+        *
+        * The text may contain speech mark language, such as Sable, JSML, or SSML,
+        * provided that the speech plugin/engine support it.  In this case,
+        * sentence parsing follows the semantics of the markup language.
+        *
+        * The job is marked speakable.
+        * If there are other speakable jobs preceeding this one in the queue,
+        * those jobs continue speaking and when finished, this job will begin speaking.
+        * If there are no other speakable jobs preceeding this one, it begins speaking.
+        *
+        * @see getTextCount
+        *
+        * @since KDE 3.5
+        */
+        virtual uint sayText(const QString &text, const QString &talker) = 0;
+
+        /**
+        * Adds another part to a text job.  Does not start speaking the text.
+        * @param text           The message to be spoken.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @return               Part number for the added part.  Parts are numbered starting at 1.
+        *
+        * The text is parsed into individual sentences.  Call getTextCount to retrieve
+        * the sentence count.  Call startText to mark the job as speakable and if the
+        * job is the first speakable job in the queue, speaking will begin.
+        *
+        * @see setText.
+        * @see startText.
+        */
+        virtual int appendText(const QString &text, uint jobNum=0) = 0;
+
+        /**
+        * Queue a text job from the contents of a file.  Does not start speaking the text.
+        * @param filename       Full path to the file to be spoken.  May be a URL.
+        * @param talker         Code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default talker.
+        *                       If no plugin has been configured for the specified Talker code,
+        *                       defaults to the closest matching talker.
+        * @param encoding       Name of the encoding to use when reading the file.  If
+        *                       NULL or Empty, uses default stream encoding.
+        * @return               Job number.  0 if an error occurs.
+        *
+        * Plain text is parsed into individual sentences using the current sentence delimiter.
+        * Call setSentenceDelimiter to change the sentence delimiter prior to calling setText.
+        * Call getTextCount to retrieve the sentence count after calling setText.
+        *
+        * The text may contain speech mark language, such as Sable, JSML, or SSML,
+        * provided that the speech plugin/engine support it.  In this case,
+        * sentence parsing follows the semantics of the markup language.
+        *
+        * Call startText to mark the job as speakable and if the
+        * job is the first speakable job in the queue, speaking will begin.
+        *
+        * @see getTextCount
+        * @see startText
+        */
+        virtual uint setFile(const QString &filename, const QString &talker,
+            const QString& encoding) = 0;
+
+        /**
+        * Get the number of sentences in a text job.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @return               The number of sentences in the job.  -1 if no such job.
+        *
+        * The sentences of a job are given sequence numbers from 1 to the number returned by this
+        * method.  The sequence numbers are emitted in the sentenceStarted and
+        * sentenceFinished signals.
+        */
+        virtual int getTextCount(uint jobNum=0) = 0;
+
+        /**
+        * Get the job number of the current text job.
+        * @return               Job number of the current text job. 0 if no jobs.
+        *
+        * Note that the current job may not be speaking. See isSpeakingText.
+        *
+        * @see getTextJobState.
+        * @see isSpeakingText
+        */
+        virtual uint getCurrentTextJob() = 0;
+
+        /**
+        * Get the number of jobs in the text job queue.
+        * @return               Number of text jobs in the queue.  0 if none.
+        */
+        virtual uint getTextJobCount() = 0;
+
+        /**
+        * Get a comma-separated list of text job numbers in the queue.
+        * @return               Comma-separated list of text job numbers in the queue.
+        */
+        virtual QString getTextJobNumbers() = 0;
+
+        /**
+        * Get the state of a text job.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @return               State of the job. -1 if invalid job number.
+        *
+        * @see kttsdJobState
+        */
+        virtual int getTextJobState(uint jobNum=0) = 0;
+
+        /**
+        * Get information about a text job.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @return               A QDataStream containing information about the job.
+        *                       Blank if no such job.
+        *
+        * The stream contains the following elements:
+        *   - int state        - Job state.
+        *   - QCString appId   - DCOP senderId of the application that requested the speech job.
+        *   - QString talker   - Talker Code requested by application.
+        *   - int seq          - Current sentence being spoken.  Sentences are numbered starting at 1.
+        *   - int sentenceCount - Total number of sentences in the job.
+        *   - int partNum      - Current part of the job begin spoken.  Parts are numbered starting at 1.
+        *   - int partCount    - Total number of parts in the job.
+        *
+        * Note that sequence numbers apply to the entire job.  They do not start from 1 at the beginning of
+        * each part.
+        *
+        * The following sample code will decode the stream:
+                @code
+                    QByteArray jobInfo = getTextJobInfo(jobNum);
+                    QDataStream stream(jobInfo, IO_ReadOnly);
+                    int state;
+                    QCString appId;
+                    QString talker;
+                    int seq;
+                    int sentenceCount;
+                    int partNum;
+                    int partCount;
+                    stream >> state;
+                    stream >> appId;
+                    stream >> talker;
+                    stream >> seq;
+                    stream >> sentenceCount;
+                    stream >> partNum;
+                    stream >> partCount;
+                @endcode
+         */
+        virtual QByteArray getTextJobInfo(uint jobNum=0) = 0;
+
+        /**
+        * Given a Talker Code, returns the Talker ID of the talker that would speak
+        * a text job with that Talker Code.
+        * @param talkerCode     Talker Code.
+        * @return               Talker ID of the talker that would speak the text job.
+        */
+        virtual QString talkerCodeToTalkerId(const QString& talkerCode) = 0;
+
+        /**
+        * Return a sentence of a job.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @param seq            Sequence number of the sentence.
+        * @return               The specified sentence in the specified job.  If no such
+        *                       job or sentence, returns "".
+        */
+        virtual QString getTextJobSentence(uint jobNum=0, uint seq=0) = 0;
+
+        /**
+        * Determine if kttsd is currently speaking any text jobs.
+        * @return               True if currently speaking any text jobs.
+        */
+        virtual bool isSpeakingText() const = 0;
+
+        /**
+        * Remove a text job from the queue.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        *
+        * The job is deleted from the queue and the textRemoved signal is emitted.
+        *
+        * If there is another job in the text queue, and it is marked speakable,
+        * that job begins speaking.
+        */
+        virtual ASYNC removeText(uint jobNum=0) = 0;
+
+        /**
+        * Start a text job at the beginning.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        *
+        * Rewinds the job to the beginning.
+        *
+        * The job is marked speakable.
+        * If there are other speakable jobs preceeding this one in the queue,
+        * those jobs continue speaking and when finished, this job will begin speaking.
+        * If there are no other speakable jobs preceeding this one, it begins speaking.
+        *
+        * The textStarted signal is emitted when the text job begins speaking.
+        * When all the sentences of the job have been spoken, the job is marked for deletion from
+        * the text queue and the textFinished signal is emitted.
+        */
+        virtual ASYNC startText(uint jobNum=0) = 0;
+
+        /**
+        * Stop a text job and rewind to the beginning.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        *
+        * The job is marked not speakable and will not be speakable until startText
+        * or resumeText is called.
+        *
+        * If there are speaking jobs preceeding this one in the queue, they continue speaking.
+        *
+        * If the job is currently speaking, the textStopped signal is emitted,
+        * the job stops speaking, and if the next job in the queue is speakable, it
+        * begins speaking.
+        *
+        * Depending upon the speech engine and plugin used, speech may not stop immediately
+        * (it might finish the current sentence).
+        */
+        virtual ASYNC stopText(uint jobNum=0) = 0;
+
+        /**
+        * Pause a text job.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        *
+        * The job is marked as paused and will not be speakable until resumeText or
+        * startText is called.
+        *
+        * If there are speaking jobs preceeding this one in the queue, they continue speaking.
+        *
+        * If the job is currently speaking, the textPaused signal is emitted and the job
+        * stops speaking.  Note that if the next job in the queue is speakable, it does
+        * not start speaking as long as this job is paused.
+        *
+        * Depending upon the speech engine and plugin used, speech may not stop immediately
+        * (it might finish the current sentence).
+        *
+        * @see resumeText
+        */
+        virtual ASYNC pauseText(uint jobNum=0) = 0;
+
+        /**
+        * Start or resume a text job where it was paused.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        *
+        * The job is marked speakable.
+        *
+        * If the job is currently speaking, or is waiting to be spoken (speakable
+        * state), the resumeText() call is ignored.
+        *
+        * If the job is currently queued, or is finished, it is the same as calling
+        * @see startText .
+        *
+        * If there are speaking jobs preceeding this one in the queue,
+        * those jobs continue speaking and when finished this job will begin
+        * speaking where it left off.
+        *
+        * The textResumed signal is emitted when the job resumes.
+        *
+        * @see pauseText
+        */
+        virtual ASYNC resumeText(uint jobNum=0) = 0;
+
+        /**
+        * Get a list of the talkers configured in KTTS.
+        * @return               A QStringList of fully-specified talker codes, one
+        *                       for each talker user has configured.
+        *
+        * @see talkers
+        */
+        virtual QStringList getTalkers() = 0;
+
+        /**
+        * Change the talker for a text job.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @param talker         New code for the talker to do the speaking.  Example "en".
+        *                       If NULL, defaults to the user's default talker.
+        *                       If no plugin has been configured for the specified Talker code,
+        *                       defaults to the closest matching talker.
+        */
+        virtual ASYNC changeTextTalker(const QString &talker, uint jobNum=0 ) = 0;
+
+        /**
+        * Get the user's default talker.
+        * @return               A fully-specified talker code.
+        *
+        * @see talkers
+        * @see getTalkers
+        */
+        virtual QString userDefaultTalker() = 0;
+
+        /**
+        * Move a text job down in the queue so that it is spoken later.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        *
+        * If the job is currently speaking, it is paused.
+        * If the next job in the queue is speakable, it begins speaking.
+        */
+        virtual ASYNC moveTextLater(uint jobNum=0) = 0;
+
+        /**
+        * Jump to the first sentence of a specified part of a text job.
+        * @param partNum        Part number of the part to jump to.  Parts are numbered starting at 1.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @return               Part number of the part actually jumped to.
+        *
+        * If partNum is greater than the number of parts in the job, jumps to last part.
+        * If partNum is 0, does nothing and returns the current part number.
+        * If no such job, does nothing and returns 0.
+        * Does not affect the current speaking/not-speaking state of the job.
+        */
+        virtual int jumpToTextPart(int partNum, uint jobNum=0) = 0;
+
+        /**
+        * Advance or rewind N sentences in a text job.
+        * @param n              Number of sentences to advance (positive) or rewind (negative) in the job.
+        * @param jobNum         Job number of the text job.
+        *                       If zero, applies to the last job queued by the application,
+        *                       but if no such job, applies to the current job (if any).
+        * @return               Sequence number of the sentence actually moved to.  Sequence numbers
+        *                       are numbered starting at 1.
+        *
+        * If no such job, does nothing and returns 0.
+        * If n is zero, returns the current sequence number of the job.
+        * Does not affect the current speaking/not-speaking state of the job.
+        */
+        virtual uint moveRelTextSentence(int n, uint jobNum=0) = 0;
+
+        /**
+        * Add the clipboard contents to the text queue and begin speaking it.
+        */
+        virtual ASYNC speakClipboard() = 0;
+
+        /**
+        * Displays the %KTTS Manager dialog.  In this dialog, the user may backup or skip forward in
+        * any text job by sentence or part, rewind jobs, pause or resume jobs, or
+        * delete jobs.
+        */
+        virtual void showDialog() = 0;
+
+        /**
+        * Stop the service.
+        */
+        virtual void kttsdExit() = 0;
+
+        /**
+        * Re-start %KTTSD.
+        */
+        virtual void reinit() = 0;
+
+        /**
+        * Return the KTTSD deamon version number.
+        * @since KDE 3.5
+        */
+        virtual QString version() = 0;
+        //@}
+
+    k_dcop_signals:
+        void ignoreThis();
+
+        /** @name DCOP Signals */
+        //@{
+
+        /**
+        * This signal is emitted when KTTSD starts or restarts after a call to reinit.
+        */
+        void kttsdStarted();
+        /**
+        * This signal is emitted just before KTTSD exits.
+        */
+        void kttsdExiting();
+        /**
+        * This signal is emitted when the speech engine/plugin encounters a marker in the text.
+        * @param appId          DCOP application ID of the application that queued the text.
+        * @param markerName     The name of the marker seen.
+        *
+        * @see markers
+        */
+        void markerSeen(const QCString& appId, const QString& markerName);
+        /**
+        * This signal is emitted whenever a sentence begins speaking.
+        * @param appId          DCOP application ID of the application that queued the text.
+        * @param jobNum         Job number of the text job.
+        * @param seq            Sequence number of the text.
+        *
+        * @see getTextCount
+        */
+        void sentenceStarted(const QCString& appId, uint jobNum, uint seq);
+        /**
+        * This signal is emitted when a sentence has finished speaking.
+        * @param appId          DCOP application ID of the application that queued the text.
+        * @param jobNum         Job number of the text job.
+        * @param seq            Sequence number of the text.
+        *
+        * @see getTextCount
+        */
+        void sentenceFinished(const QCString& appId, uint jobNum, uint seq);
+
+        /**
+        * This signal is emitted whenever a new text job is added to the queue.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        */
+        void textSet(const QCString& appId, uint jobNum);
+
+        /**
+        * This signal is emitted whenever a new part is appended to a text job.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        * @param partNum        Part number of the new part.  Parts are numbered starting
+        *                       at 1.
+        */
+        void textAppended(const QCString& appId, uint jobNum, int partNum);
+
+        /**
+        * This signal is emitted whenever speaking of a text job begins.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        */
+        void textStarted(const QCString& appId, uint jobNum);
+        /**
+        * This signal is emitted whenever a text job is finished.  The job has
+        * been marked for deletion from the queue and will be deleted when another
+        * job reaches the Finished state. (Only one job in the text queue may be
+        * in state Finished at one time.)  If startText or resumeText is
+        * called before the job is deleted, it will remain in the queue for speaking.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        */
+        void textFinished(const QCString& appId, uint jobNum);
+        /**
+        * This signal is emitted whenever a speaking text job stops speaking.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        *
+        * The signal is only emitted if stopText() is called and the job is currently
+        * speaking.
+        */
+        void textStopped(const QCString& appId, uint jobNum);
+        /**
+        * This signal is emitted whenever a speaking text job is paused.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        */
+        void textPaused(const QCString& appId, uint jobNum);
+        /**
+        * This signal is emitted when a text job, that was previously paused, resumes speaking.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        */
+        void textResumed(const QCString& appId, uint jobNum);
+        /**
+        * This signal is emitted whenever a text job is deleted from the queue.
+        * The job is no longer in the queue when this signal is emitted.
+        * @param appId          The DCOP senderId of the application that created the job.
+        * @param jobNum         Job number of the text job.
+        */
+        void textRemoved(const QCString& appId, uint jobNum);
+        //@}
+};
+
+#endif // _KSPEECH_H_