kttsd/libkttsd/talkercode.h

   1 /***************************************************** vim:set ts=4 sw=4 sts=4:
   2   Object containing a Talker Code and providing convenience
   3   functions for manipulating Talker Codes.
   4   For an explanation of what a Talker Code is, see speech.h.
   5   -------------------
   6   Copyright:
   7   (C) 2005 by Gary Cramblitt <garycramblitt@comcast.net>
   8   -------------------
   9   Original author: Gary Cramblitt <garycramblitt@comcast.net>
  10
  11   This program is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   This program is distributed in the hope that it will be useful,
  17   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19   GNU General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with this program; if not, write to the Free Software
  23   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  24  ******************************************************************************/
  25
  26 #ifndef TALKERCODE_H
  27 #define TALKERCODE_H
  28
  29 // Qt includes.
  30 #include <QtCore/QList>
  31 #include <QtCore/QString>
  32
  33 // KDE includes.
  34 #include <kdemacros.h>
  35
  36 class KDE_EXPORT TalkerCode
  37 {
  38     public:
  39         /**
  40          * Constructor.
  41          */
  42         explicit TalkerCode(const QString &code=QString(), bool normal=false);
  43         /**
  44          * Copy Constructor.
  45          */
  46         explicit TalkerCode(TalkerCode* talker, bool normal=false);
  47
  48         /**
  49          * Destructor.
  50          */
  51         ~TalkerCode();
  52
  53         typedef QList<TalkerCode> TalkerCodeList;
  54
  55         /**
  56          * Properties.
  57          */
  58         QString id() const;                 /* ID */
  59         QString languageCode() const;       /* lang="xx" */
  60         QString countryCode() const;        /* lang="yy_xx */
  61         QString voice() const;              /* name="xxx" */
  62         QString gender() const;             /* gender="xxx" */
  63         QString volume() const;             /* volume="xxx" */
  64         QString rate() const;               /* rate="xxx" */
  65         QString plugInName() const;         /* synthesizer="xxx" */
  66         QString desktopEntryName() const;
  67
  68         /**
  69          * Returns the language code plus country code (if any).
  70          */
  71         QString fullLanguageCode() const;
  72
  73         void setId(const QString& id);
  74         void setLanguageCode(const QString &languageCode);
  75         void setCountryCode(const QString &countryCode);
  76         void setVoice(const QString &voice);
  77         void setGender(const QString &gender);
  78         void setVolume(const QString &volume);
  79         void setRate(const QString &rate);
  80         void setPlugInName(const QString plugInName);
  81         void setDesktopEntryName(const QString &desktopEntryName);
  82
  83         /**
  84          * Sets the language code and country code (if given).
  85          */
  86         void setFullLanguageCode(const QString &fullLanguageCode);
  87
  88         /**
  89          * The Talker Code returned in XML format.
  90          */
  91         void setTalkerCode(const QString& code);
  92         QString getTalkerCode() const;
  93
  94         /**
  95          * The Talker Code translated for display.
  96          */
  97         QString getTranslatedDescription() const;
  98
  99         /**
 100          * Normalizes the Talker Code by filling in defaults.
 101          */
 102         void normalize();
 103
 104         /**
 105          * Given a talker code, normalizes it into a standard form and also returns
 106          * the full language code.
 107          * @param talkerCode         Unnormalized talker code.
 108          * @return fullLanguageCode  Language code from the talker code (including country code if any).
 109          * @return                   Normalized talker code.
 110          */
 111         static QString normalizeTalkerCode(const QString &talkerCode, QString &fullLanguageCode);
 112
 113         /**
 114          * Given a language code that might contain a country code, splits the code into
 115          * the two letter language code and country code.
 116          * @param fullLanguageCode   Language code to be split.
 117          * @return languageCode      Just the language part of the code.
 118          * @return countryCode       The country code part (if any).
 119          *
 120          * If the input code begins with an asterisk, it is ignored and removed from the returned
 121          * languageCode.
 122          */
 123         static void splitFullLanguageCode(const QString &lang, QString &languageCode, QString &countryCode);
 124
 125         /**
 126          * Given a language code and plugin name, returns a normalized default talker code.
 127          * @param fullLanguageCode      Language code.
 128          * @param plugInName            Name of the Synthesizer plugin.
 129          * @return                      Full normalized talker code.
 130          *
 131          * Example returned from defaultTalkerCode("en", "Festival")
 132          *   <voice lang="en" name="fixed" gender="neutral"/>
 133          *   <prosody volume="medium" rate="medium"/>
 134          *   <kttsd synthesizer="Festival" />
 135          */
 136         static QString defaultTalkerCode(const QString &fullLanguageCode, const QString &plugInName);
 137
 138         /**
 139          * Converts a language code plus optional country code to language description.
 140          */
 141         static QString languageCodeToLanguage(const QString &languageCode);
 142
 143         /**
 144          * These functions return translated Talker Code attributes.
 145          */
 146         static QString translatedGender(const QString &gender);
 147         static QString translatedVolume(const QString &volume);
 148         static QString translatedRate(const QString &rate);
 149         static QString untranslatedGender(const QString &gender);
 150         static QString untranslatedVolume(const QString &volume);
 151         static QString untranslatedRate(const QString &rate);
 152
 153         /**
 154          * Given a list of parsed talker codes and a desired talker code, finds the closest
 155          * matching talker in the list.
 156          * @param talkers                       The list of parsed talker codes.
 157          * @param talker                        The desired talker code.
 158          * @param assumeDefaultLang             If true, and desired talker code lacks a language code,
 159          *                                      the default language is assumed.
 160          * @return                              Index into talkers of the closest matching talker.
 161          */
 162         static int findClosestMatchingTalker(
 163             const TalkerCodeList& talkers,
 164             const QString& talker,
 165             bool assumeDefaultLang = true);
 166
 167         /**
 168          * Strips leading * from a code.
 169          */
 170         static QString stripPrefer( const QString& code, bool& preferred);
 171
 172         /**
 173         * Uses KTrader to convert a translated Synth Plugin Name to DesktopEntryName.
 174         * @param name                   The translated plugin name.  From Name= line in .desktop file.
 175         * @return                       DesktopEntryName.  The name of the .desktop file (less .desktop).
 176         *                               QString() if not found.
 177         */
 178         static QString TalkerNameToDesktopEntryName(const QString& name);
 179
 180         /**
 181         * Uses KTrader to convert a DesktopEntryName into a translated Synth Plugin Name.
 182         * @param desktopEntryName       The DesktopEntryName.
 183         * @return                       The translated Name of the plugin, from Name= line in .desktop file.
 184         */
 185         static QString TalkerDesktopEntryNameToName(const QString& desktopEntryName);
 186
 187     private:
 188         /**
 189          * Given a talker code, parses out the attributes.
 190          * @param talkerCode       The talker code.
 191          */
 192         void parseTalkerCode(const QString &talkerCode);
 193
 194         QString m_id;
 195         QString m_languageCode;       /* lang="xx" */
 196         QString m_countryCode;        /* lang="yy_xx */
 197         QString m_voice;              /* name="xxx" */
 198         QString m_gender;             /* gender="xxx" */
 199         QString m_volume;             /* volume="xxx" */
 200         QString m_rate;               /* rate="xxx" */
 201         QString m_plugInName;         /* synthesizer="xxx" */
 202         QString m_desktopEntryName;
 203 };
 204
 205 #endif      // TALKERCODE_H