PlugInConf Class Reference
pluginconf - the KDE Text-to-Speech Deamon Plugin Configuration API. More...
#include <pluginconf.h>
Public Slots | |
void | configChanged () |
Signals | |
void | changed (bool) |
Public Member Functions | |
PlugInConf (QWidget *parent=0, const char *name=0) | |
virtual | ~PlugInConf () |
virtual void | load (KConfig *config, const QString &configGroup) |
virtual void | save (KConfig *config, const QString &configGroup) |
virtual void | defaults () |
virtual bool | supportsMultiInstance () |
virtual void | setDesiredLanguage (const QString &lang) |
virtual QString | getTalkerCode () |
virtual QStringList | getSupportedLanguages () |
void | setPlayer (TestPlayer *player) |
TestPlayer * | getPlayer () |
Static Public Member Functions | |
QString | realFilePath (const QString &filename) |
Protected Member Functions | |
QString | getLocation (const QString &name) |
QString | splitLanguageCode (const QString &languageCode, QString &countryCode) |
Protected Attributes | |
QStringList | m_path |
TestPlayer * | m_player |
Detailed Description
pluginconf - the KDE Text-to-Speech Deamon Plugin Configuration API.
- Version:
- 1.0 Draft 2
- Warning:
- The pluginconf interface is still being developed and is likely to change in the future.
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 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.
Multiple Instances
If it is possible to run multiple simultaneous instances of your synthesis engine, return True from the 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 supportsMultiInstance.
Language Support
Some plugins support only one language. For them, return the appropriate language code when 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 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, 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 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 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 getTalkerCode (see below). Note that you should not limit the users choices based on the 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 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 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 getTalkerCode is called.
Talker Codes
Review the section on Talkers in kspeech.h.When your plugin is added to the KTTSMGR, getSupportedLanguages will be called followed by setDesiredLanguage and load. Note that the configuration file will most likely be empty when load is called.
Next, 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 QString::null. Note that 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 getTalkerCode().
Here is guidance for what you should return for each of the talker attributes when getTalkerCode is called:
- 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 QString::null 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".
- 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.
- gender. May be "male", "female", or "neutral".
- name. The voice code. If your plugin does not support voices, return "fixed".
- volume. May be "medium", "loud", or "soft". If your plugin does not support configurable volume, return "medium".
- 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 changed signal, 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 setDesiredLanguage call. It is possible that setDesiredLanguage is Null. That is OK. In this case, KTTSMGR will prompt the user for the language code.
Load and Save Methods
The load and 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 config object and a configGroup string.Plugins that do not support multiple instances (return False from 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.
setDesiredLanguage is always called just prior to load, therefore it is not necessary to save the language code, unless your plugin needs it in order to synthesize speech.
Definition at line 209 of file pluginconf.h.
Constructor & Destructor Documentation
|
Constructor.
Definition at line 39 of file pluginconf.cpp. References m_path. |
|
Destructor.
Definition at line 50 of file pluginconf.cpp. |
Member Function Documentation
|
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.
Definition at line 68 of file pluginconf.cpp. |
|
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.
Definition at line 82 of file pluginconf.cpp. |
|
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. Definition at line 93 of file pluginconf.cpp. |
|
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.
Definition at line 106 of file pluginconf.cpp. |
|
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 QString::null, no specific language has been chosen.
Definition at line 118 of file pluginconf.cpp. |
|
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 QString::null.
Definition at line 127 of file pluginconf.cpp. |
|
Return a list of all the languages possibly supported by the plugin. If your plugin can support any language, return Null.
Definition at line 140 of file pluginconf.cpp. |
|
Player object that can be used by the plugin for testing playback of synthed files.
Definition at line 203 of file pluginconf.cpp. |
|
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 changed signal. Definition at line 339 of file pluginconf.h. References changed(). |
|
This signal indicates that the configuration has been changed. It should be emitted whenever user changes something in the configuration widget. Referenced by configChanged(). |
|
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.
Definition at line 148 of file pluginconf.cpp. References m_path. |
|
Breaks a language code into the language code and country code (if any).
Definition at line 178 of file pluginconf.cpp. |
Member Data Documentation
|
The system path in a QStringList.
Definition at line 370 of file pluginconf.h. Referenced by getLocation(), and PlugInConf(). |
The documentation for this class was generated from the following files: