You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdeaccessibility/kttsd/libkttsd/pluginconf.h

380 lines
18 KiB

/***************************************************** vim:set ts=4 sw=4 sts=4:
This file is the template for the configuration plug ins.
-------------------
Copyright : (C) 2002-2003 by José Pablo Ezequiel "Pupeno" Fernández
-------------------
Original author: José Pablo Ezequiel "Pupeno" Fernández <pupeno@kde.org>
Current Maintainer: Gary Cramblitt <garycramblitt@comcast.net>
******************************************************************************/
/***************************************************************************
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; version 2 of the License. *
* *
***************************************************************************/
#ifndef _PLUGINCONF_H_
#define _PLUGINCONF_H_
// TQt includes.
#include <tqwidget.h>
// KDE includes.
#include <kconfig.h>
#include <kdebug.h>
#include <kdemacros.h>
#include "kdeexportfix.h"
// KTTS includes.
#include "testplayer.h"
/**
* @interface PlugInConf
*
* pluginconf - the KDE Text-to-Speech Deamon Plugin Configuration API.
*
* @version 1.0 Draft 2
*
* This class defines the interface that plugins to KTTSMGR must implement.
*
* @warning The pluginconf interface is still being developed and is likely
* to change in the future.
*
* A KTTSD Plugin interfaces between KTTSD and a speech engine.
* A PlugInConf provides an on-screen widget for configuring the plugin for use
* with KTTSD.
*
* @section guidelines General Guidelines
*
* - The configuration widget should be no larger than TODO pixels.
* - Do not supply Load, Save, Cancel, or OK buttons. Those are provided by KTTSMGR.
* - Try to supply a Test button so that users can test the configuration before
* saving it.
* - Your configuration widget will be running inside a KPart.
* - Whenever the user changes something in your on-screen widget, emit the
* @ref changed signal.
* - If a plugin can automatically configure itself, i.e., locate voice files,
* set default values, etc., it should do so when it is first added to KTTSMGR.
*
* @section multiinstance Multiple Instances
*
* If it is possible to run multiple simultaneous instances of your synthesis engine,
* return True from the @ref supportsMultiInstance method. The user will be able to
* configure multiple instances of your plugin, each with a different set of
* talker attributes.
*
* If you cannot run multiple simultaneous instances of your synthesis engine,
* or your plugin has a fixed set of talker attributes (only one language, voice,
* gender, volume, and speed), return False from @ref supportsMultiInstance.
*
* @section language Language Support
*
* Some plugins support only one language. For them, return the appropriate language
* code when @ref getSupportedLanguages is called.
*
* If your plugin can support multiple languages, your task is a little more
* complicated. The best way to handle this is to install a @e voices file with
* your plugin that lists all the supported languages, voice files, genders, etc.
* that are possible. When your plugin is added to KTTSMGR,
* @ref getSupportedLanguages will be called. Return a list of all the possible
* languages supported, even if the user hasn't yet picked a voice file in your
* configuration, or even told your where the voice files are.
*
* There are three ways that users and applications pick a language code for your
* plugin:
* - The user picks a code from among the languages you returned in
* @ref getSupportedLanguages, or
* - The user picks your plugin and uses your configuration widget to pick a voice
* file or other configuration option that determines the language, or
* - An application requests a plugin with specific language support.
*
* If possible, avoid making the user pick a language code in your plugin.
*
* In the first and third cases, the chosen language code will be passed to your
* plugin when @ref setDesiredLanguage is called. If you can satisfy this
* language code, good, but it is possible that once the user has begun
* configuring your plugin, you find that you cannot support the desired
* language. Perhaps a needed voice file is missing. That is OK.
* You'll inform KTTSMGR of the actual language code when KTTSMGR
* calls @ref getTalkerCode (see below). Note that you should not limit the
* users choices based on the @ref setDesiredLanguage. A user might start
* out configuring your plugin for one language, and then change his or her
* mind to a different language.
*
* Also note that language codes may also include an appended country code.
* For example, "en_GB" for British English. When @ref getSupportedLanguages is
* called, you should return as specific a list as possible. For example,
* if your plugin supports both American and British English, your returned
* list would include "en_GB" and "en_US". When @ref setDesiredLanguage is
* called, a country code may or may not be included. If included and your
* plugin supports the language, but not the specific country variant,
* your plugin should nevertheless attempt to satisfy the request, returning
* the actual supported language and country when @ref getTalkerCode is called.
*
* @section talkercodes Talker Codes
*
* Review the section on Talkers in kspeech.h.
*
* When your plugin is added to the KTTSMGR, @ref getSupportedLanguages
* will be called followed by @ref setDesiredLanguage and @ref load.
* Note that the configuration file will most likely be empty when
* @ref load is called.
* Next, @ref getTalkerCode
* will be called. If your plugin can automatically configure itself to the desired
* language, it should do so and return a fully-specified talker code. If your
* plugin is not yet ready and requires user help, return TQString(). Note that
* @ref setDesiredLanguage may be Null, in which case, you should allow the
* user to configure your plugin to any of your supported languages.
*
* When your plugin has been configured enough to begin synthesis, return a
* fully-specified talker code in @ref getTalkerCode().
*
* Here is guidance for what you should return for each of the talker attributes
* when @ref getTalkerCode is called:
*
* - @e lang. If user has completed configuring your plugin, i.e., it is
* ready to begin synthesizing, return the ISO 639-1 language code
* for the language it can synthesize. If your plugin is not yet
* fully configured, you should return TQString() for the entire
* talker code. If your plugin supports a specific national version
* of a language, that should also be included using the ISO 3166
* country code separated from the language code by underscore (_).
* For example, if your plugin synthesizes American English, you would
* return "en_US". If British English, "en_BR". And if
* non-specific English, just "en".
* - @e synthesizer. The name of your plugin. Keep short, but long enough to
* distinquish different implementations. For example,
* Festival Int, Flite, Hadifix. Use only letters, numbers
* spaces, and underscores (_) in your plugin name.
* - @e gender. May be "male", "female", or "neutral".
* - @e name. The voice code. If your plugin does not support voices,
* return "fixed".
* - @e volume. May be "medium", "loud", or "soft". If your plugin does not support
* configurable volume, return "medium".
* - @e rate. May be "medium", "fast", or "slow". If your plugin does not support
* configurable speed, return "medium".
*
* The order of the attributes you return does not matter. Here is an example of
* a fully-specified talker code.
*
* lang="en" name="Kal" gender="male" volume="soft" rate="fast"
* synthesizer="Festival Interactive"
*
* Do not return translated values for the Talker Code attributes. All English.
*
* Each time your plugin emits the @ref changed signal, @ref getTalkerCode will be called.
* The configuration dialog OK button will be disabled until you return a non-null
* Talker Code.
*
* It is possible that your plugin does not know the language supported. The generic
* Command plugin is example of such a case, since the user enters an arbitrary command.
* In this case, return the value from the @ref setDesiredLanguage call. It is possible
* that @ref setDesiredLanguage is Null. That is OK. In this case, KTTSMGR will prompt
* the user for the language code.
*
* @section loadandsavemethods Load and Save Methods
*
* The @ref load and @ref save methods are called by KTTSMGR so that your plugin
* can load and save configuration options from the configuration file.
* These methods have two parameters, a @e config object and a @e configGroup string.
*
* Plugins that do not support multiple instances (return False from
* @ref supportsMultiInstance), should simply call config->setGroup(configGroup)
* before loading or saving their configuration.
*
* If your plugin supports multiple instances, it is slightly more complicated.
* Typically, there will be configuration options that apply to all instances
* of the plugin and there will be options that apply only to the specific
* configured instance of the plugin. To load or save the instance-specific
* options, call config->setGroup(configGroup). For options that apply
* to all instances of the plugin, call config->setGroup() with a group name
* that contains your plugin's name. For example,
* config->setGroup("Festival Defaults").
*
* For example, when first added to KTTSMGR, the Festival plugin needs to know the path to
* the directory containing all the installed voice files. It is best for a plugin
* to try to locate these resources automatically, but if it can't find them,
* when the user has told it where they are, it is a good idea to save this information
* in the all-instances group. In this way, the next time the plugin
* is added to KTTSMGR, or another instance is added, it will be able to find them
* automatically.
*
* @ref setDesiredLanguage is always called just prior to @ref load, therefore
* it is not necessary to save the language code, unless your plugin needs it in
* order to synthesize speech.
*/
class KDE_EXPORT PlugInConf : public TQWidget{
Q_OBJECT
public:
/**
* Constructor
*/
PlugInConf( TQWidget *parent = 0, const char *name = 0);
/**
* Destructor
*/
virtual ~PlugInConf();
/**
* This method is invoked whenever the module should read its
* configuration (most of the times from a config file) and update the
* user interface. This happens when the user clicks the "Reset" button in
* the control center, to undo all of his changes and restore the currently
* valid settings. Note that KTTSMGR calls this when the plugin is
* loaded, so it not necessary to call it in your constructor.
* The plugin should read its configuration from the specified group
* in the specified config file.
* @param config Pointer to a KConfig object.
* @param configGroup Call config->setGroup with this argument before
* loading your configuration.
*
* When a plugin is first added to KTTSMGR, @e load will be called with
* a Null @e configGroup. In this case, the plugin will not have
* any instance-specific parameters to load, but it may still wish
* to load parameters that apply to all instances of the plugin.
*
* @see loadandsavemethods
*/
virtual void load(KConfig *config, const TQString &configGroup);
/**
* This function gets called when the user wants to save the settings in
* the user interface, updating the config files or wherever the
* configuration is stored. The method is called when the user clicks "Apply"
* or "Ok". The plugin should save its configuration in the specified
* group of the specified config file.
* @param config Pointer to a KConfig object.
* @param configGroup Call config->setGroup with this argument before
* saving your configuration.
*
* @ref setDesiredLanguage is always called just prior to @ref load, therefore
* it is not necessary to save the language code, unless your plugin needs it in
* order to synthesize speech.
*/
virtual void save(KConfig *config, const TQString &configGroup);
/**
* This function is called to set the settings in the module to sensible
* default values. It gets called when hitting the "Default" button. The
* default values should probably be the same as the ones the application
* uses when started without a config file. Note that defaults should
* be applied to the on-screen widgets; not to the config file.
*/
virtual void defaults();
/**
* Indicates whether the plugin supports multiple instances. Return
* False if only one instance of the plugin can run at a time, or
* if your plugin is limited to a single language, voice, gender, volume,
* and speed.
* @return True if multiple instances are possible.
*/
virtual bool supportsMultiInstance();
/**
* This function informs the plugin of the desired language to be spoken
* by the plugin. The plugin should attempt to adapt itself to the
* specified language code, choosing sensible defaults if necessary.
* If the passed-in code is TQString(), no specific language has
* been chosen.
* @param lang The desired language code or Null if none.
*
* If the plugin is unable to support the desired language, that is OK.
* Language codes are given by ISO 639-1 and are in lowercase.
* The code may also include an ISO 3166 country code in uppercase
* separated from the language code by underscore (_). For
* example, en_GB. If your plugin supports the given language, but
* not the given country, treat it as though the country
* code were not specified, i.e., adapt to the given language.
*/
virtual void setDesiredLanguage(const TQString &lang);
/**
* Return fully-specified talker code for the configured plugin. This code
* uniquely identifies the configured instance of the plugin and distinquishes
* one instance from another. If the plugin has not been fully configured,
* i.e., cannot yet synthesize, return TQString().
* @return Fully-specified talker code.
*/
virtual TQString getTalkerCode();
/**
* Return a list of all the languages possibly supported by the plugin.
* If your plugin can support any language, return Null.
* @return A TQStringList of supported language and optional country
* codes, or Null if any.
*
* The languge codes are given in ISO 639-1. Lowercase should be used.
* If your plugin supports various national forms of a language, ISO 3166
* country codes should also be include in upperase and separated from
* the language code with underscore (_). Examples:
* en
* en_US
* en_GB
* es
* es_CL
* The list you return should be as specific as practicable.
*/
virtual TQStringList getSupportedLanguages();
/**
* Player object that can be used by the plugin for testing playback of synthed files.
*/
void setPlayer(TestPlayer* player);
TestPlayer* getPlayer();
static TQString realFilePath(const TQString &filename);
static TQString testMessage(const TQString& languageCode);
public slots:
/**
* This slot is used internally when the configuration is changed. It is
* typically connected to signals from the widgets of the configuration
* and should emit the @ref changed signal.
*/
void configChanged(){
kdDebug() << "PlugInConf::configChanged: Running"<< endl;
emit changed(true);
};
signals:
/**
* This signal indicates that the configuration has been changed.
* It should be emitted whenever user changes something in the configuration widget.
*/
void changed(bool);
protected:
/**
* Searches the $PATH variable for any file. If that file exists in the PATH, or
* is contained in any directory in the PATH, it returns the full path to it.
* @param name The name of the file to search for.
* @returns The path to the file on success, a blank TQString
* if its not found.
*/
TQString getLocation(const TQString &name);
/**
* Breaks a language code into the language code and country code (if any).
* @param languageCode Language code.
* @return countryCode Just the country code part (if any).
* @return Just the language code part.
*/
TQString splitLanguageCode(const TQString& languageCode, TQString& countryCode);
/// The system path in a TQStringList.
TQStringList m_path;
TestPlayer* m_player;
};
#endif //_PLUGINCONF_H_