From a9b417e9bfea3da908884c726ffc9bf4f64691cf Mon Sep 17 00:00:00 2001 From: Jean-Michel Trivi Date: Fri, 11 Sep 2009 18:34:02 -0700 Subject: [PATCH] TextToSpeech javadoc update. --- .../java/android/speech/tts/TextToSpeech.java | 197 ++++++++++-------- 1 file changed, 115 insertions(+), 82 deletions(-) diff --git a/core/java/android/speech/tts/TextToSpeech.java b/core/java/android/speech/tts/TextToSpeech.java index a6d76d684fe4e..3f369ddd580a1 100755 --- a/core/java/android/speech/tts/TextToSpeech.java +++ b/core/java/android/speech/tts/TextToSpeech.java @@ -35,9 +35,13 @@ import java.util.Locale; /** * * Synthesizes speech from text for immediate playback or to create a sound file. + *

A TextToSpeech instance can only be used to synthesize text once it has completed its + * initialization. Implement the {@link TextToSpeech.OnInitListener} to be + * notified of the completion of the initialization.
+ * When you are done using the TextToSpeech instance, call the {@link #shutdown()} method + * to release the native resources used by the TextToSpeech engine. * */ -//TODO complete javadoc + add links to constants public class TextToSpeech { /** @@ -85,7 +89,7 @@ public class TextToSpeech { public static final int LANG_MISSING_DATA = -1; /** - * Denotes the language is not supported by the current TTS engine. + * Denotes the language is not supported. */ public static final int LANG_NOT_SUPPORTED = -2; @@ -100,29 +104,38 @@ public class TextToSpeech { /** - * Called when the TTS has initialized. - * - * The InitListener must implement the onInit function. onInit is passed a - * status code indicating the result of the TTS initialization. + * Interface definition of a callback to be invoked indicating the completion of the + * TextToSpeech engine initialization. */ public interface OnInitListener { + /** + * Called to signal the completion of the TextToSpeech engine initialization. + * @param status {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. + */ public void onInit(int status); } /** - * Called when the TTS has completed saying something that has an utterance ID set. + * Interface definition of a callback to be invoked indicating the TextToSpeech engine has + * completed synthesizing an utterance with an utterance ID set. * - * The OnUtteranceCompletedListener must implement the onUtteranceCompleted function. - * onUtteranceCompleted is passed a String that is the utteranceId given in - * the original speak call. */ - public interface OnUtteranceCompletedListener { + public interface OnUtteranceCompletedListener { + /** + * Called to signal the completion of the synthesis of the utterance that was identified + * with the string parameter. This identifier is the one originally passed in the + * parameter hashmap of the synthesis request in + * {@link TextToSpeech#speak(String, int, HashMap)} or + * {@link TextToSpeech#synthesizeToFile(String, HashMap, String)} with the + * {@link TextToSpeech.Engine#KEY_PARAM_UTTERANCE_ID} key. + * @param utteranceId the identifier of the utterance. + */ public void onUtteranceCompleted(String utteranceId); } /** - * Internal constants for the TTS functionality + * Internal constants for the TextToSpeech functionality * */ public class Engine { @@ -145,38 +158,41 @@ public class TextToSpeech { public static final String DEFAULT_SYNTH = "com.svox.pico"; // default values for rendering + /** + * Default audio stream used when playing synthesized speech. + */ public static final int DEFAULT_STREAM = AudioManager.STREAM_MUSIC; // return codes for a TTS engine's check data activity /** * Indicates success when checking the installation status of the resources used by the - * text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. + * TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. */ public static final int CHECK_VOICE_DATA_PASS = 1; /** * Indicates failure when checking the installation status of the resources used by the - * text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. + * TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. */ public static final int CHECK_VOICE_DATA_FAIL = 0; /** * Indicates erroneous data when checking the installation status of the resources used by - * the text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. + * the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. */ public static final int CHECK_VOICE_DATA_BAD_DATA = -1; /** * Indicates missing resources when checking the installation status of the resources used - * by the text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. + * by the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. */ public static final int CHECK_VOICE_DATA_MISSING_DATA = -2; /** * Indicates missing storage volume when checking the installation status of the resources - * used by the text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. + * used by the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent. */ public static final int CHECK_VOICE_DATA_MISSING_VOLUME = -3; // intents to ask engine to install data or check its data /** - * Activity Action: Triggers the platform Text-To-Speech engine to + * Activity Action: Triggers the platform TextToSpeech engine to * start the activity that installs the resource files on the device * that are required for TTS to be operational. Since the installation * of the data can be interrupted or declined by the user, the application @@ -197,7 +213,7 @@ public class TextToSpeech { public static final String ACTION_TTS_DATA_INSTALLED = "android.speech.tts.engine.TTS_DATA_INSTALLED"; /** - * Activity Action: Starts the activity from the platform Text-To-Speech + * Activity Action: Starts the activity from the platform TextToSpeech * engine to verify the proper installation and availability of the * resource files on the system. Upon completion, the activity will * return one of the following codes: @@ -210,9 +226,9 @@ public class TextToSpeech { * fields: *