2 // C++ Interface: ksayit_ttsplugin
7 // Author: Robert Vogl <voglrobe@lapislazuli>, (C) 2004
9 // Copyright: See COPYING file that comes with this distribution
13 #ifndef KSAYIT_TTSPLUGIN
14 #define KSAYIT_TTSPLUGIN
17 #include <QtCore/QObject>
18 #include <QtGui/QWidget>
19 #include <QtGui/QFrame>
23 // App specific includes
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
41 TTSPlugin* createPlugin(KApplication *Appl)
43 return new MyNewPlugin(Appl);
46 void destroyPlugin(TTSPlugin* p)
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.
60 class TTSPlugin
: public QObject
63 TTSPlugin(QObject
*parent
, const char *name
) : QObject(parent
, name
){};
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.
72 virtual QString
getName_KS() const = 0;
74 /** Returns the description of the plugin.\n
75 * Has to be reimplemented by the plugin implementation.
77 virtual QString
getDescription_KS() const = 0;
79 /** Returns the supported control actions of the plugin.
80 * It is represented as an OR'ed value of enum \pACTIONS.
82 virtual int getActions_KS() = 0;
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
89 virtual const QWidget
* getGUI_KS(QFrame
*frame
) = 0;
91 /** Let the plugin (re)load its configuration
93 virtual void reloadConfiguration_KS() = 0;
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.
99 virtual bool saveWasClicked_KS() const = 0;
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
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.
114 virtual QString
sayText_KS(const QString
&text
) = 0;
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
120 * If configurable, \p TTS::AUDIOFILE must toggle synchronously with
122 * This flag must have a valid value during the overall lifetime
123 * of the plugin object.
125 virtual int getStatus_KS() const = 0;
127 /** Processes the stop event from KSayIt.
129 virtual void stop_KS() = 0;
131 /** Processes the pause event from KSayIt.
133 virtual void pause_KS() = 0;
135 /** Processes resume event after pause from KSayIt.
137 virtual void resume_KS() = 0;
139 /** May be used as a fast forward function, e.g.
140 * jump to the next sentence, paragraph or whatever.
142 virtual void ffwd_KS() = 0;
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.
148 virtual void frev_KS() = 0;
152 // Types of the class factories
153 typedef TTSPlugin
* (*create_ttspi
)(KApplication
*Appl
);
154 typedef void (*destroy_ttspi
)(TTSPlugin
*p
);