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