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 Steet, Fifth Floor, Boston, MA  02110-1301, USA.
  24  ******************************************************************************/
  25
  26 #ifndef _TALKERCODE_H_
  27 #define _TALKERCODE_H_
  28
  29 // Qt includes.
  30 #include <qstring.h>
  31 #include <kdemacros.h>
  32 #include "kdeexportfix.h"
  33 #include <q3valuelist.h>
  34
  35 class KDE_EXPORT TalkerCode
  36 {
  37     public:
  38         /**
  39          * Constructor.
  40          */
  41         TalkerCode(const QString &code=QString::null, bool normal=false);
  42         /**
  43          * Copy Constructor.
  44          */
  45         TalkerCode(TalkerCode* talker, bool normal=false);
  46
  47         /**
  48          * Destructor.
  49          */
  50         ~TalkerCode();
  51
  52         typedef Q3ValueList<TalkerCode> TalkerCodeList;
  53
  54         /**
  55          * Properties.
  56          */
  57         QString languageCode() const;       /* lang="xx" */
  58         QString countryCode() const;        /* lang="yy_xx */
  59         QString voice() const;              /* name="xxx" */
  60         QString gender() const;             /* gender="xxx" */
  61         QString volume() const;             /* volume="xxx" */
  62         QString rate() const;               /* rate="xxx" */
  63         QString plugInName() const;         /* synthesizer="xxx" */
  64
  65         /**
  66          * Returns the language code plus country code (if any).
  67          */
  68         QString fullLanguageCode() const;
  69
  70         void setLanguageCode(const QString &languageCode);
  71         void setCountryCode(const QString &countryCode);
  72         void setVoice(const QString &voice);
  73         void setGender(const QString &gender);
  74         void setVolume(const QString &volume);
  75         void setRate(const QString &rate);
  76         void setPlugInName(const QString plugInName);
  77
  78         /**
  79          * Sets the language code and country code (if given).
  80          */
  81         void setFullLanguageCode(const QString &fullLanguageCode);
  82
  83         /**
  84          * The Talker Code returned in XML format.
  85          */
  86         QString getTalkerCode() const;
  87
  88         /**
  89          * The Talker Code translated for display.
  90          */
  91         QString getTranslatedDescription() const;
  92
  93         /**
  94          * Normalizes the Talker Code by filling in defaults.
  95          */
  96         void normalize();
  97
  98         /**
  99          * Given a talker code, normalizes it into a standard form and also returns
 100          * the full language code.
 101          * @param talkerCode         Unnormalized talker code.
 102          * @return fullLanguageCode  Language code from the talker code (including country code if any).
 103          * @return                   Normalized talker code.
 104          */
 105         static QString normalizeTalkerCode(const QString &talkerCode, QString &fullLanguageCode);
 106
 107         /**
 108          * Given a language code that might contain a country code, splits the code into
 109          * the two letter language code and country code.
 110          * @param fullLanguageCode   Language code to be split.
 111          * @return languageCode      Just the language part of the code.
 112          * @return countryCode       The country code part (if any).
 113          *
 114          * If the input code begins with an asterisk, it is ignored and removed from the returned
 115          * languageCode.
 116          */
 117         static void splitFullLanguageCode(const QString &lang, QString &languageCode, QString &countryCode);
 118
 119         /**
 120          * Given a language code and plugin name, returns a normalized default talker code.
 121          * @param fullLanguageCode      Language code.
 122          * @param plugInName            Name of the Synthesizer plugin.
 123          * @return                      Full normalized talker code.
 124          *
 125          * Example returned from defaultTalkerCode("en", "Festival")
 126          *   <voice lang="en" name="fixed" gender="neutral"/>
 127          *   <prosody volume="medium" rate="medium"/>
 128          *   <kttsd synthesizer="Festival" />
 129          */
 130         static QString defaultTalkerCode(const QString &fullLanguageCode, const QString &plugInName);
 131
 132         /**
 133          * Converts a language code plus optional country code to language description.
 134          */
 135         static QString languageCodeToLanguage(const QString &languageCode);
 136
 137         /**
 138          * These functions return translated Talker Code attributes.
 139          */
 140         static QString translatedGender(const QString &gender);
 141         static QString translatedVolume(const QString &volume);
 142         static QString translatedRate(const QString &rate);
 143         static QString untranslatedGender(const QString &gender);
 144         static QString untranslatedVolume(const QString &volume);
 145         static QString untranslatedRate(const QString &rate);
 146
 147         /**
 148          * Given a list of parsed talker codes and a desired talker code, finds the closest
 149          * matching talker in the list.
 150          * @param talkers                       The list of parsed talker codes.
 151          * @param talker                        The desired talker code.
 152          * @param assumeDefaultLang             If true, and desired talker code lacks a language code,
 153          *                                      the default language is assumed.
 154          * @return                              Index into talkers of the closest matching talker.
 155          */
 156         static int findClosestMatchingTalker(
 157             const TalkerCodeList& talkers,
 158             const QString& talker,
 159             bool assumeDefaultLang = true);
 160
 161         /**
 162          * Strips leading * from a code.
 163          */
 164         static QString stripPrefer( const QString& code, bool& preferred);
 165
 166         /**
 167         * Uses KTrader to convert a translated Synth Plugin Name to DesktopEntryName.
 168         * @param name                   The translated plugin name.  From Name= line in .desktop file.
 169         * @return                       DesktopEntryName.  The name of the .desktop file (less .desktop).
 170         *                               QString::null if not found.
 171         */
 172         static QString TalkerNameToDesktopEntryName(const QString& name);
 173
 174         /**
 175         * Uses KTrader to convert a DesktopEntryName into a translated Synth Plugin Name.
 176         * @param desktopEntryName       The DesktopEntryName.
 177         * @return                       The translated Name of the plugin, from Name= line in .desktop file.
 178         */
 179         static QString TalkerDesktopEntryNameToName(const QString& desktopEntryName);
 180
 181     private:
 182         /**
 183          * Given a talker code, parses out the attributes.
 184          * @param talkerCode       The talker code.
 185          */
 186         void parseTalkerCode(const QString &talkerCode);
 187
 188         QString m_languageCode;       /* lang="xx" */
 189         QString m_countryCode;        /* lang="yy_xx */
 190         QString m_voice;              /* name="xxx" */
 191         QString m_gender;             /* gender="xxx" */
 192         QString m_volume;             /* volume="xxx" */
 193         QString m_rate;               /* rate="xxx" */
 194         QString m_plugInName;         /* synthesizer="xxx" */
 195 };
 196
 197 #endif      // _TALKERCODE_H_