summaryrefslogtreecommitdiffstats
path: root/ksayit/src/ksayit_ttsplugin.h
blob: 68179d7a51c80ebb93c3b1f400a8f94debdb38df (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
//
// C++ Interface: ksayit_ttsplugin
//
// Description: 
//
//
// Author: Robert Vogl <voglrobe@lapislazuli>, (C) 2004
//
// Copyright: See COPYING file that comes with this distribution
//
//

#ifndef KSAYIT_TTSPLUGIN
#define KSAYIT_TTSPLUGIN

// QT includes
#include <tqobject.h>
#include <tqwidget.h>
#include <tqframe.h>
#include <tqstring.h>


// KDE includes
#include <kapplication.h>

// App specific includes


#include "kttsdlib.h"

/** TTSPlugin is an abstract class to integrate various TTS systems as plugins
 *  (Shared Objects) into KSayIt.
 *  If you would like to implement a plugin, simply make a class
 *  inherited from TTSPlugin, include 'ksayit_ttsplugin.h' and reimplement all the
 *  pure virtual functions provided herein.
 *  In addition you must implement two class factories:\n
 *  \p createPlugin() returns a pointer to an instance of your class.
 *  The Plugin Handler of KSayIt calls this function with a parameter pointing
 *  to the main application instance, as delivered by \p KApplication::kApplication().
 *  This pointer can be used for any reason i.e. to install a TQt translator.\n
 *  An instance of your class should be deleted by use of \p destroyPlugin().\n
 *  Example:
 \code
    extern "C"
    {
        TTSPlugin* createPlugin(KApplication *Appl)
        {
            return new MyNewPlugin(Appl);
        }
        
        void destroyPlugin(TTSPlugin* p)
        {
            delete p;
        }
    };
 \endcode
 *  KSayIt expects two TQt-signals from the plugin:\n
 *  \p signalPluginFinished() must be emitted when the plugin is finished,
 *  i.e. a task to speak text has been finished.\n
 *  \p signalPluginFailed() is optional and shall emitted if the processing
 *  of the plugin has been failed by any reason.
 \author Robert Vogl
 */

class TTSPlugin : public TQObject
{
protected:
    TTSPlugin(TQObject *parent, const char *name) : TQObject(parent, name){};
    
public:
    /** Returns the name of the plugin. This name is the unique identifier
     *  for the plugin. A expressive name is recommended because this name
     *  may be shown to the user, i.e. in a configuration dialog.
     *  The PluginHandler internally references to each TTS plugin by this name.\n
     *  Has to be reimplemented by the plugin implementation.
     */
    virtual TQString getName_KS() const = 0;
    
    /** Returns the description of the plugin.\n
     *  Has to be reimplemented by the plugin implementation.
     */
    virtual  TQString getDescription_KS() const = 0;
    
    /** Returns the supported control actions of the plugin.
     *  It is represented as an OR'ed value of enum \pACTIONS. 
     */
    virtual int getActions_KS() = 0;
     
    /** Returnes a pointer to the GUI widget to configure the plugin.\n
     *  Will be deleted by the PluginHandler.\n
     *  \param frame A pointer to the TQFrame object in which the dialog will
     *  be embedded.
     */
    virtual const TQWidget* getGUI_KS(TQFrame *frame) = 0;
       
    /** Let the plugin (re)load its configuration
     */
    virtual void reloadConfiguration_KS() = 0;
     
    /** Called from the Plugin Handler if the "OK" Button of the main
     *  configuartion dialog was clicked.\n
     *  Returns false if something went wrong otherwise true.
     */
    virtual bool saveWasClicked_KS() const = 0;
    
    /** This method speeches the given Text.\n
     *  If the used TTS system outputs to a sound file
     *  (i.e. a .wav file) it may return its path and filename to KSayIt. 
     *  In this case, KSayIt uses a built-in audio player to play back
     *  the file via aRts.\n
     *  If this plugin provides its own audio output mechanisms, then return
     *  \p TQString().\n
     *  The TTS processing shall be implemented non-blocking, i.e. this function has
     *  to return a valid string as soon as possible, before the typically time
     *  consuming TTS processing starts. The synchronization with KSayIt shall
     *  be performed by the status flags (see \p getStatus_KS()).
     *  \param text The text to speach. 
     */
    virtual TQString sayText_KS(const TQString &text) = 0;
    
    /** Returns an OR'ed value of status bits of the plugin.\n
     *  Currently only \p TTS::AUDIOFILE is defined.\n This
     *  bit indicates that the plugin is configured to output
     *  to an audiofile.\n
     *  If configurable, \p TTS::AUDIOFILE must toggle synchronously with
     *  the setup widget.
     *  This flag must have a valid value during the overall lifetime
     *  of the plugin object. 
     */
    virtual int getStatus_KS() const = 0;
    
    /** Processes the stop event from KSayIt.
     */
    virtual void stop_KS() = 0;
    
    /** Processes the pause event from KSayIt.
     */
    virtual void pause_KS() = 0;
    
    /** Processes resume event after pause from KSayIt.
     */
    virtual void resume_KS() = 0;
    
    /** May be used as a fast forward function, e.g.
     *  jump to the next sentence, paragraph or whatever.
     */
    virtual void ffwd_KS() = 0;
    
    /** May be used as a rewind function, e.g.
     *  jumb back to the beginning of the current paragraph,
     *  repeat previous sentence or whatever.
     */
    virtual void frev_KS() = 0;

};

// Types of the class factories
typedef TTSPlugin* (*create_ttspi)(KApplication *Appl);
typedef void (*destroy_ttspi)(TTSPlugin *p);




#endif