ksayit/src/ksayit_ttsplugin.h

   1 //
   2 // C++ Interface: ksayit_ttsplugin
   3 //
   4 // Description:
   5 //
   6 //
   7 // Author: Robert Vogl <voglrobe@lapislazuli>, (C) 2004
   8 //
   9 // Copyright: See COPYING file that comes with this distribution
  10 //
  11 //
  12
  13 #ifndef KSAYIT_TTSPLUGIN
  14 #define KSAYIT_TTSPLUGIN
  15
  16 // QT includes
  17 #include <QtCore/QObject>
  18 #include <QtGui/QWidget>
  19 #include <QtGui/QFrame>
  20
  21 // KDE includes
  22
  23 // App specific includes
  24 #include "kttsdlib.h"
  25
  26 /** TTSPlugin is an abstract class to integrate various TTS systems as plugins
  27  *  (Shared Objects) into KSayIt.
  28  *  If you would like to implement a plugin, simply make a class
  29  *  inherited from TTSPlugin, include 'ksayit_ttsplugin.h' and reimplement all the
  30  *  pure virtual functions provided herein.
  31  *  In addition you must implement two class factories:\n
  32  *  \p createPlugin() returns a pointer to an instance of your class.
  33  *  The Plugin Handler of KSayIt calls this function with a parameter pointing
  34  *  to the main application instance, as delivered by \p KApplication::kApplication().
  35  *  This pointer can be used for any reason i.e. to install a Qt translator.\n
  36  *  An instance of your class should be deleted by use of \p destroyPlugin().\n
  37  *  Example:
  38  \code
  39     extern "C"
  40     {
  41         TTSPlugin* createPlugin(KApplication *Appl)
  42         {
  43             return new MyNewPlugin(Appl);
  44         }
  45
  46         void destroyPlugin(TTSPlugin* p)
  47         {
  48             delete p;
  49         }
  50     };
  51  \endcode
  52  *  KSayIt expects two Qt-signals from the plugin:\n
  53  *  \p signalPluginFinished() must be emitted when the plugin is finished,
  54  *  i.e. a task to speak text has been finished.\n
  55  *  \p signalPluginFailed() is optional and shall emitted if the processing
  56  *  of the plugin has been failed by any reason.
  57  \author Robert Vogl
  58  */
  59
  60 class TTSPlugin : public QObject
  61 {
  62 protected:
  63     TTSPlugin(QObject *parent, const char *name) : QObject(parent, name){};
  64
  65 public:
  66     /** Returns the name of the plugin. This name is the unique identifier
  67      *  for the plugin. A expressive name is recommended because this name
  68      *  may be shown to the user, i.e. in a configuration dialog.
  69      *  The PluginHandler internally references to each TTS plugin by this name.\n
  70      *  Has to be reimplemented by the plugin implementation.
  71      */
  72     virtual QString getName_KS() const = 0;
  73
  74     /** Returns the description of the plugin.\n
  75      *  Has to be reimplemented by the plugin implementation.
  76      */
  77     virtual  QString getDescription_KS() const = 0;
  78
  79     /** Returns the supported control actions of the plugin.
  80      *  It is represented as an OR'ed value of enum \pACTIONS.
  81      */
  82     virtual int getActions_KS() = 0;
  83
  84     /** Returnes a pointer to the GUI widget to configure the plugin.\n
  85      *  Will be deleted by the PluginHandler.\n
  86      *  \param frame A pointer to the QFrame object in which the dialog will
  87      *  be embedded.
  88      */
  89     virtual const QWidget* getGUI_KS(QFrame *frame) = 0;
  90
  91     /** Let the plugin (re)load its configuration
  92      */
  93     virtual void reloadConfiguration_KS() = 0;
  94
  95     /** Called from the Plugin Handler if the "OK" Button of the main
  96      *  configuartion dialog was clicked.\n
  97      *  Returns false if something went wrong otherwise true.
  98      */
  99     virtual bool saveWasClicked_KS() const = 0;
 100
 101     /** This method speeches the given Text.\n
 102      *  If the used TTS system outputs to a sound file
 103      *  (i.e. a .wav file) it may return its path and filename to KSayIt.
 104      *  In this case, KSayIt uses a built-in audio player to play back
 105      *  the file via aRts.\n
 106      *  If this plugin provides its own audio output mechanisms, then return
 107      *  \p QString().\n
 108      *  The TTS processing shall be implemented non-blocking, i.e. this function has
 109      *  to return a valid string as soon as possible, before the typically time
 110      *  consuming TTS processing starts. The synchronization with KSayIt shall
 111      *  be performed by the status flags (see \p getStatus_KS()).
 112      *  \param text The text to speach.
 113      */
 114     virtual QString sayText_KS(const QString &text) = 0;
 115
 116     /** Returns an OR'ed value of status bits of the plugin.\n
 117      *  Currently only \p TTS::AUDIOFILE is defined.\n This
 118      *  bit indicates that the plugin is configured to output
 119      *  to an audiofile.\n
 120      *  If configurable, \p TTS::AUDIOFILE must toggle synchronously with
 121      *  the setup widget.
 122      *  This flag must have a valid value during the overall lifetime
 123      *  of the plugin object.
 124      */
 125     virtual int getStatus_KS() const = 0;
 126
 127     /** Processes the stop event from KSayIt.
 128      */
 129     virtual void stop_KS() = 0;
 130
 131     /** Processes the pause event from KSayIt.
 132      */
 133     virtual void pause_KS() = 0;
 134
 135     /** Processes resume event after pause from KSayIt.
 136      */
 137     virtual void resume_KS() = 0;
 138
 139     /** May be used as a fast forward function, e.g.
 140      *  jump to the next sentence, paragraph or whatever.
 141      */
 142     virtual void ffwd_KS() = 0;
 143
 144     /** May be used as a rewind function, e.g.
 145      *  jumb back to the beginning of the current paragraph,
 146      *  repeat previous sentence or whatever.
 147      */
 148     virtual void frev_KS() = 0;
 149
 150 };
 151
 152 // Types of the class factories
 153 typedef TTSPlugin* (*create_ttspi)(KApplication *Appl);
 154 typedef void (*destroy_ttspi)(TTSPlugin *p);
 155
 156
 157
 158
 159 #endif
 160
 161