kttsd/libkttsd/filterproc.h

   1 /***************************************************** vim:set ts=4 sw=4 sts=4:
   2   Filter Processing class.
   3   This is the interface definition for text filters.
   4   -------------------
   5   Copyright:
   6   (C) 2005 by Gary Cramblitt <garycramblitt@comcast.net>
   7   -------------------
   8   Original author: Gary Cramblitt <garycramblitt@comcast.net>
   9
  10   This program is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU General Public License as published by
  12   the Free Software Foundation; either version 2 of the License, or
  13   (at your option) any later version.
  14
  15   This program is distributed in the hope that it will be useful,
  16   but WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18   GNU General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with this program; if not, write to the Free Software
  22   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  23  ******************************************************************************/
  24
  25 #ifndef _FILTERPROC_H_
  26 #define _FILTERPROC_H_
  27
  28 // Qt includes.
  29 #include <QObject>
  30
  31
  32 // KDE includes.
  33 #include <kdemacros.h>
  34
  35 class TalkerCode;
  36 class KConfig;
  37 class KConfigGroup;
  38
  39 class KDE_EXPORT KttsFilterProc : public QObject
  40 {
  41     Q_OBJECT
  42
  43 public:
  44     enum FilterState {
  45         fsIdle = 0,              // Not doing anything.  Ready to filter.
  46         fsFiltering = 1,         // Filtering.
  47         fsStopping = 2,          // Stop of filtering is in progress.
  48         fsFinished = 3           // Filtering finished.
  49     };
  50
  51     /**
  52      * Constructor.
  53      */
  54     KttsFilterProc( QObject *parent );
  55
  56     /**
  57      * Destructor.
  58      */
  59     virtual ~KttsFilterProc();
  60
  61     /**
  62      * Initialize the filter.
  63      * @param config          Settings object.
  64      * @param configGroup     Settings Group.
  65      * @return                False if filter is not ready to filter.
  66      *
  67      * Note: The parameters are for reading from kttsdrc file.  Plugins may wish to maintain
  68      * separate configuration files of their own.
  69      */
  70     virtual bool init(const KConfigGroup &config);
  71
  72     /**
  73      * Returns True if this filter is a Sentence Boundary Detector.
  74      * If so, the filter should implement @ref setSbRegExp() .
  75      * @return          True if this filter is a SBD.
  76      */
  77     virtual bool isSBD();
  78
  79      /**
  80       * Returns True if the plugin supports asynchronous processing,
  81       * i.e., supports asyncConvert method.
  82       * @return                        True if this plugin supports asynchronous processing.
  83       *
  84       * If the plugin returns True, it must also implement @ref getState .
  85       * It must also emit @ref filteringFinished when filtering is completed.
  86       * If the plugin returns True, it must also implement @ref stopFiltering .
  87       * It must also emit @ref filteringStopped when filtering has been stopped.
  88       */
  89     virtual bool supportsAsync();
  90
  91     /**
  92      * Convert input, returning output.  Runs synchronously.
  93      * @param inputText         Input text.
  94      * @param talkerCode        TalkerCode structure for the talker that KTTSD intends to
  95      *                          use for synthing the text.  Useful for extracting hints about
  96      *                          how to filter the text.  For example, languageCode.
  97      * @param appId             The DCOP appId of the application that queued the text.
  98      *                          Also useful for hints about how to do the filtering.
  99      */
 100     virtual QString convert(const QString& inputText, TalkerCode* talkerCode, const QString& appId);
 101
 102     /**
 103      * Convert input.  Runs asynchronously.
 104      * @param inputText         Input text.
 105      * @param talkerCode        TalkerCode structure for the talker that KTTSD intends to
 106      *                          use for synthing the text.  Useful for extracting hints about
 107      *                          how to filter the text.  For example, languageCode.
 108      * @param appId             The DCOP appId of the application that queued the text.
 109      *                          Also useful for hints about how to do the filtering.
 110      * @return                  False if the filter cannot perform the conversion.
 111      *
 112      * When conversion is completed, emits signal @ref filteringFinished.  Calling
 113      * program may then call @ref getOutput to retrieve converted text.  Calling
 114      * program must call @ref ackFinished to acknowledge the conversion.
 115      */
 116     virtual bool asyncConvert(const QString& inputText, TalkerCode* talkerCode, const QString& appId);
 117
 118     /**
 119      * Waits for a previous call to asyncConvert to finish.
 120      */
 121     virtual void waitForFinished();
 122
 123     /**
 124      * Returns the state of the Filter.
 125      */
 126     virtual int getState();
 127
 128     /**
 129      * Returns the filtered output.
 130      */
 131     virtual QString getOutput();
 132
 133     /**
 134      * Acknowledges the finished filtering.
 135      */
 136     virtual void ackFinished();
 137
 138     /**
 139      * Stops filtering.  The filteringStopped signal will emit when filtering
 140      * has in fact stopped and state returns to fsIdle;
 141      */
 142     virtual void stopFiltering();
 143
 144     /**
 145      * Did this filter do anything?  If the filter returns the input as output
 146      * unmolested, it should return False when this method is called.
 147      */
 148     virtual bool wasModified();
 149
 150     /**
 151      * Set Sentence Boundary Regular Expression.
 152      * This method will only be called if the application overrode the default.
 153      *
 154      * @param re            The sentence delimiter regular expression.
 155      */
 156     virtual void setSbRegExp(const QString& re);
 157
 158 signals:
 159     /**
 160      * Emitted when asynchronous filtering has completed.
 161      */
 162     void filteringFinished();
 163
 164     /**
 165      * Emitted when stopFiltering has been called and filtering has in fact stopped.
 166      */
 167     void filteringStopped();
 168
 169     /**
 170      * If an error occurs, Filter should signal the error and return input as output in
 171      * convert method.  If Filter should not be called in the future, perhaps because
 172      * it could not find its configuration file, return False for keepGoing.
 173      * @param keepGoing         False if the filter should not be called in the future.
 174      * @param msg               Error message.
 175      */
 176     void error(bool keepGoing, const QString &msg);
 177 };
 178
 179 #endif      // _FILTERPROC_H_