/*
* Copyright (C) 2014 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.text.style;
import java.text.NumberFormat;
import java.util.Locale;
import android.os.Parcel;
import android.os.PersistableBundle;
import android.text.ParcelableSpan;
import android.text.TextUtils;
/**
* A span that supplies additional meta-data for the associated text intended
* for text-to-speech engines. If the text is being processed by a
* text-to-speech engine, the engine may use the data in this span in addition
* to or instead of its associated text.
*
* Each instance of a TtsSpan has a type, for example {@link #TYPE_DATE}
* or {@link #TYPE_MEASURE}. And a list of arguments, provided as
* key-value pairs in a bundle.
*
* The inner classes are there for convenience and provide builders for each
* TtsSpan type.
*/
public class TtsSpan implements ParcelableSpan {
private final String mType;
private final PersistableBundle mArgs;
/**
* This span type can be used to add morphosyntactic features to the text it
* spans over, or synthesize a something else than the spanned text. Use
* the argument {@link #ARG_TEXT} to set a different text.
* Accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
* {@link #ARG_CASE}.
*/
public static final String TYPE_TEXT = "android.type.text";
/**
* The text associated with this span is a cardinal. Must include the
* number to be synthesized with {@link #ARG_NUMBER}.
* Also accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
* {@link #ARG_CASE}.
*/
public static final String TYPE_CARDINAL = "android.type.cardinal";
/**
* The text associated with this span is an ordinal. Must include the
* number to be synthesized with {@link #ARG_NUMBER}.
* Also accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
* {@link #ARG_CASE}.
*/
public static final String TYPE_ORDINAL = "android.type.ordinal";
/**
* The text associated with this span is a decimal number. Must include the
* number to be synthesized with {@link #ARG_INTEGER_PART} and
* {@link #ARG_FRACTIONAL_PART}.
* Also accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
* {@link #ARG_CASE}.
*/
public static final String TYPE_DECIMAL = "android.type.decimal";
/**
* The text associated with this span is a fractional number. Must include
* the number to be synthesized with {@link #ARG_NUMERATOR} and
* {@link #ARG_DENOMINATOR}. {@link #ARG_INTEGER_PART} is optional
* Also accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
* {@link #ARG_CASE}.
*/
public static final String TYPE_FRACTION = "android.type.fraction";
/**
* The text associated with this span is a measure, consisting of a number
* and a unit. The number can be a cardinal, decimal or a fraction. Set the
* number with the same arguments as {@link #TYPE_CARDINAL},
* {@link #TYPE_DECIMAL} or {@link #TYPE_FRACTION}. The unit can be
* specified with {@link #ARG_UNIT}.
* Also accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
* {@link #ARG_CASE}.
*/
public static final String TYPE_MEASURE = "android.type.measure";
/**
* The text associated with this span is a time, consisting of a number of
* hours and minutes, specified with {@link #ARG_HOURS} and
* {@link #ARG_MINUTES}.
* Also accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
* {@link #ARG_CASE}.
*/
public static final String TYPE_TIME = "android.type.time";
/**
* The text associated with this span is a date. At least one of the
* arguments {@link #ARG_MONTH} and {@link #ARG_YEAR} has to be provided.
* The argument {@link #ARG_DAY} is optional if {@link #ARG_MONTH} is set.
* The argument {@link #ARG_WEEKDAY} is optional if {@link #ARG_DAY} is set.
* Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
* {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
*/
public static final String TYPE_DATE = "android.type.date";
/**
* The text associated with this span is a telephone number. The argument
* {@link #ARG_NUMBER_PARTS} is required. {@link #ARG_COUNTRY_CODE} and
* {@link #ARG_EXTENSION} are optional.
* Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
* {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
*/
public static final String TYPE_TELEPHONE = "android.type.telephone";
/**
* The text associated with this span is a URI (can be used for URLs and
* email addresses). The full schema for URLs, which email addresses can
* effectively be seen as a subset of, is:
* protocol://username:password@domain:port/path?query_string#fragment_id
* Hence populating just username and domain will read as an email address.
* All arguments are optional, but at least one has to be provided:
* {@link #ARG_PROTOCOL}, {@link #ARG_USERNAME}, {@link #ARG_PASSWORD},
* {@link #ARG_DOMAIN}, {@link #ARG_PORT}, {@link #ARG_PATH},
* {@link #ARG_QUERY_STRING} and {@link #ARG_FRAGMENT_ID}.
* Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
* {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
*/
public static final String TYPE_ELECTRONIC = "android.type.electronic";
/**
* The text associated with this span is an amount of money. Set the amount
* with the same arguments as {@link #TYPE_DECIMAL}.
* {@link #ARG_CURRENCY} is used to set the currency. {@link #ARG_QUANTITY}
* is optional.
* Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
* {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
*/
public static final String TYPE_MONEY = "android.type.money";
/**
* The text associated with this span is a series of digits that have to be
* read sequentially. The digits can be set with {@link #ARG_DIGITS}.
* Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
* {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
*/
public static final String TYPE_DIGITS = "android.type.digits";
/**
* The text associated with this span is a series of characters that have to
* be read verbatim. The engine will attempt to read out any character like
* punctuation but excluding whitespace. {@link #ARG_VERBATIM} is required.
* Also accepts the arguments {@link #ARG_GENDER},
* {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
*/
public static final String TYPE_VERBATIM = "android.type.verbatim";
/**
* String argument supplying gender information. Can be any of
* {@link #GENDER_NEUTRAL}, {@link #GENDER_MALE} and
* {@link #GENDER_FEMALE}.
*/
public static final String ARG_GENDER = "android.arg.gender";
public static final String GENDER_NEUTRAL = "android.neutral";
public static final String GENDER_MALE = "android.male";
public static final String GENDER_FEMALE = "android.female";
/**
* String argument supplying animacy information. Can be
* {@link #ANIMACY_ANIMATE} or
* {@link #ANIMACY_INANIMATE}
*/
public static final String ARG_ANIMACY = "android.arg.animacy";
public static final String ANIMACY_ANIMATE = "android.animate";
public static final String ANIMACY_INANIMATE = "android.inanimate";
/**
* String argument supplying multiplicity information. Can be any of
* {@link #MULTIPLICITY_SINGLE}, {@link #MULTIPLICITY_DUAL} and
* {@link #MULTIPLICITY_PLURAL}
*/
public static final String ARG_MULTIPLICITY = "android.arg.multiplicity";
public static final String MULTIPLICITY_SINGLE = "android.single";
public static final String MULTIPLICITY_DUAL = "android.dual";
public static final String MULTIPLICITY_PLURAL = "android.plural";
/**
* String argument supplying case information. Can be any of
* {@link #CASE_NOMINATIVE}, {@link #CASE_ACCUSATIVE}, {@link #CASE_DATIVE},
* {@link #CASE_ABLATIVE}, {@link #CASE_GENITIVE}, {@link #CASE_VOCATIVE},
* {@link #CASE_LOCATIVE} and {@link #CASE_INSTRUMENTAL}
*/
public static final String ARG_CASE = "android.arg.case";
public static final String CASE_NOMINATIVE = "android.nominative";
public static final String CASE_ACCUSATIVE = "android.accusative";
public static final String CASE_DATIVE = "android.dative";
public static final String CASE_ABLATIVE = "android.ablative";
public static final String CASE_GENITIVE = "android.genitive";
public static final String CASE_VOCATIVE = "android.vocative";
public static final String CASE_LOCATIVE = "android.locative";
public static final String CASE_INSTRUMENTAL = "android.instrumental";
/**
* String supplying the text to be synthesized. The synthesizer is free
* to decide how to interpret the text.
* Can be used with {@link #TYPE_TEXT}.
*/
public static final String ARG_TEXT = "android.arg.text";
/**
* Argument used to specify a whole number. The value can be a string of
* digits of any size optionally prefixed with a - or +.
* Can be used with {@link #TYPE_CARDINAL} and {@link #TYPE_ORDINAL}.
*/
public static final String ARG_NUMBER = "android.arg.number";
/**
* Argument used to specify the integer part of a decimal or fraction. The
* value can be a string of digits of any size optionally prefixed with
* a - or +.
* Can be used with {@link #TYPE_DECIMAL} and {@link #TYPE_FRACTION}.
*/
public static final String ARG_INTEGER_PART = "android.arg.integer_part";
/**
* Argument used to specify the fractional part of a decimal. The value can
* be a string of digits of any size.
* Can be used with {@link #TYPE_DECIMAL}.
*/
public static final String ARG_FRACTIONAL_PART =
"android.arg.fractional_part";
/**
* Argument used to choose the suffix (thousand, million, etc) that is used
* to pronounce large amounts of money. For example it can be used to
* disambiguate between "two thousand five hundred dollars" and
* "two point five thousand dollars".
* If implemented, engines should support at least "1000", "1000000",
* "1000000000" and "1000000000000".
* Example: if the {@link #ARG_INTEGER_PART} argument is "10", the
* {@link #ARG_FRACTIONAL_PART} argument is "4", the {@link #ARG_QUANTITY}
* argument is "1000" and the {@link #ARG_CURRENCY} argument is "usd", the
* TTS engine may pronounce the span as "ten point four thousand dollars".
* With the same example but with the quantity set as "1000000" the TTS
* engine may pronounce the span as "ten point four million dollars".
* Can be used with {@link #TYPE_MONEY}.
*/
public static final String ARG_QUANTITY =
"android.arg.quantity";
/**
* Argument used to specify the numerator of a fraction. The value can be a
* string of digits of any size optionally prefixed with a - or +.
* Can be used with {@link #TYPE_FRACTION}.
*/
public static final String ARG_NUMERATOR = "android.arg.numerator";
/**
* Argument used to specify the denominator of a fraction. The value can be
* a string of digits of any size optionally prefixed with a + or -.
* Can be used with {@link #TYPE_FRACTION}.
*/
public static final String ARG_DENOMINATOR = "android.arg.denominator";
/**
* Argument used to specify the unit of a measure. The unit should always be
* specified in English singular form. Prefixes may be used. Engines will do
* their best to pronounce them correctly in the language used. Engines are
* expected to at least support the most common ones like "meter", "second",
* "degree celsius" and "degree fahrenheit" with some common prefixes like
* "milli" and "kilo".
* Can be used with {@link #TYPE_MEASURE}.
*/
public static final String ARG_UNIT = "android.arg.unit";
/**
* Argument used to specify the hours of a time. The hours should be
* provided as an integer in the range from 0 up to and including 24.
* Can be used with {@link #TYPE_TIME}.
*/
public static final String ARG_HOURS = "android.arg.hours";
/**
* Argument used to specify the minutes of a time. The hours should be
* provided as an integer in the range from 0 up to and including 59.
* Can be used with {@link #TYPE_TIME}.
*/
public static final String ARG_MINUTES = "android.arg.minutes";
/**
* Argument used to specify the weekday of a date. The value should be
* provided as an integer and can be any of {@link #WEEKDAY_SUNDAY},
* {@link #WEEKDAY_MONDAY}, {@link #WEEKDAY_TUESDAY},
* {@link #WEEKDAY_WEDNESDAY}, {@link #WEEKDAY_THURSDAY},
* {@link #WEEKDAY_FRIDAY} and {@link #WEEKDAY_SATURDAY}.
* Can be used with {@link #TYPE_DATE}.
*/
public static final String ARG_WEEKDAY = "android.arg.weekday";
public static final int WEEKDAY_SUNDAY = 1;
public static final int WEEKDAY_MONDAY = 2;
public static final int WEEKDAY_TUESDAY = 3;
public static final int WEEKDAY_WEDNESDAY = 4;
public static final int WEEKDAY_THURSDAY = 5;
public static final int WEEKDAY_FRIDAY = 6;
public static final int WEEKDAY_SATURDAY = 7;
/**
* Argument used to specify the day of the month of a date. The value should
* be provided as an integer in the range from 1 up to and including 31.
* Can be used with {@link #TYPE_DATE}.
*/
public static final String ARG_DAY = "android.arg.day";
/**
* Argument used to specify the month of a date. The value should be
* provided as an integer and can be any of {@link #MONTH_JANUARY},
* {@link #MONTH_FEBRUARY}, {@link #MONTH_MARCH}, {@link #MONTH_APRIL},
* {@link #MONTH_MAY}, {@link #MONTH_JUNE}, {@link #MONTH_JULY},
* {@link #MONTH_AUGUST}, {@link #MONTH_SEPTEMBER}, {@link #MONTH_OCTOBER},
* {@link #MONTH_NOVEMBER} and {@link #MONTH_DECEMBER}.
* Can be used with {@link #TYPE_DATE}.
*/
public static final String ARG_MONTH = "android.arg.month";
public static final int MONTH_JANUARY = 0;
public static final int MONTH_FEBRUARY = 1;
public static final int MONTH_MARCH = 2;
public static final int MONTH_APRIL = 3;
public static final int MONTH_MAY = 4;
public static final int MONTH_JUNE = 5;
public static final int MONTH_JULY = 6;
public static final int MONTH_AUGUST = 7;
public static final int MONTH_SEPTEMBER = 8;
public static final int MONTH_OCTOBER = 9;
public static final int MONTH_NOVEMBER = 10;
public static final int MONTH_DECEMBER = 11;
/**
* Argument used to specify the year of a date. The value should be provided
* as a positive integer.
* Can be used with {@link #TYPE_DATE}.
*/
public static final String ARG_YEAR = "android.arg.year";
/**
* Argument used to specify the country code of a telephone number. Can be
* a string of digits optionally prefixed with a "+".
* Can be used with {@link #TYPE_TELEPHONE}.
*/
public static final String ARG_COUNTRY_CODE = "android.arg.country_code";
/**
* Argument used to specify the main number part of a telephone number. Can
* be a string of digits where the different parts of the telephone number
* can be separated with a space, '-', '/' or '.'.
* Can be used with {@link #TYPE_TELEPHONE}.
*/
public static final String ARG_NUMBER_PARTS = "android.arg.number_parts";
/**
* Argument used to specify the extension part of a telephone number. Can be
* a string of digits.
* Can be used with {@link #TYPE_TELEPHONE}.
*/
public static final String ARG_EXTENSION = "android.arg.extension";
/**
* Argument used to specify the protocol of a URI. Examples are "http" and
* "ftp".
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_PROTOCOL = "android.arg.protocol";
/**
* Argument used to specify the username part of a URI. Should be set as a
* string.
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_USERNAME = "android.arg.username";
/**
* Argument used to specify the password part of a URI. Should be set as a
* string.
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_PASSWORD = "android.arg.password";
/**
* Argument used to specify the domain part of a URI. For example
* "source.android.com".
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_DOMAIN = "android.arg.domain";
/**
* Argument used to specify the port number of a URI. Should be specified as
* an integer.
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_PORT = "android.arg.port";
/**
* Argument used to specify the path part of a URI. For example
* "source/index.html".
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_PATH = "android.arg.path";
/**
* Argument used to specify the query string of a URI. For example
* "arg=value&argtwo=value".
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_QUERY_STRING = "android.arg.query_string";
/**
* Argument used to specify the fragment id of a URI. Should be specified as
* a string.
* Can be used with {@link #TYPE_ELECTRONIC}.
*/
public static final String ARG_FRAGMENT_ID = "android.arg.fragment_id";
/**
* Argument used to specify the currency. Should be a ISO4217 currency code,
* e.g. "USD".
* Can be used with {@link #TYPE_MONEY}.
*/
public static final String ARG_CURRENCY = "android.arg.money";
/**
* Argument used to specify a string of digits.
* Can be used with {@link #TYPE_DIGITS}.
*/
public static final String ARG_DIGITS = "android.arg.digits";
/**
* Argument used to specify a string where the characters are read verbatim,
* except whitespace.
* Can be used with {@link #TYPE_VERBATIM}.
*/
public static final String ARG_VERBATIM = "android.arg.verbatim";
public TtsSpan(String type, PersistableBundle args) {
mType = type;
mArgs = args;
}
public TtsSpan(Parcel src) {
mType = src.readString();
mArgs = src.readPersistableBundle();
}
/**
* Returns the type.
* @return The type of this instance.
*/
public String getType() {
return mType;
}
/**
* Returns a bundle of the arguments set.
* @return The bundle of the arguments set.
*/
public PersistableBundle getArgs() {
return mArgs;
}
@Override
public int describeContents() {
return 0;
}
@Override
public void writeToParcel(Parcel dest, int flags) {
writeToParcelInternal(dest, flags);
}
/** @hide */
public void writeToParcelInternal(Parcel dest, int flags) {
dest.writeString(mType);
dest.writePersistableBundle(mArgs);
}
@Override
public int getSpanTypeId() {
return getSpanTypeIdInternal();
}
/** @hide */
public int getSpanTypeIdInternal() {
return TextUtils.TTS_SPAN;
}
/**
* A simple builder for TtsSpans.
* This builder can be used directly, but the more specific subclasses of
* this builder like {@link TtsSpan.TextBuilder} and
* {@link TtsSpan.CardinalBuilder} are likely more useful.
*
* This class uses generics so methods from this class can return instances
* of its child classes, resulting in a fluent API (CRTP pattern).
*/
public static class Builder<C extends Builder<?>> {
// Holds the type of this class.
private final String mType;
// Holds the arguments of this class. It only stores objects of type
// String, Integer and Long.
private PersistableBundle mArgs = new PersistableBundle();
public Builder(String type) {
mType = type;
}
/**
* Returns a TtsSpan built from the parameters set by the setter
* methods.
* @return A TtsSpan built with parameters of this builder.
*/
public TtsSpan build() {
return new TtsSpan(mType, mArgs);
}
/**
* Sets an argument to a string value.
* @param arg The argument name.
* @param value The value the argument should be set to.
* @return This instance.
*/
@SuppressWarnings("unchecked")
public C setStringArgument(String arg, String value) {
mArgs.putString(arg, value);
return (C) this;
}
/**
* Sets an argument to an int value.
* @param arg The argument name.
* @param value The value the argument should be set to.
*/
@SuppressWarnings("unchecked")
public C setIntArgument(String arg, int value) {
mArgs.putInt(arg, value);
return (C) this;
}
/**
* Sets an argument to a long value.
* @param arg The argument name.
* @param value The value the argument should be set to.
*/
@SuppressWarnings("unchecked")
public C setLongArgument(String arg, long value) {
mArgs.putLong(arg, value);
return (C) this;
}
}
/**
* A builder for TtsSpans, has setters for morphosyntactic features.
* This builder can be used directly, but the more specific subclasses of
* this builder like {@link TtsSpan.TextBuilder} and
* {@link TtsSpan.CardinalBuilder} are likely more useful.
*/
public static class SemioticClassBuilder<C extends SemioticClassBuilder<?>>
extends Builder<C> {
public SemioticClassBuilder(String type) {
super(type);
}
/**
* Sets the gender information for this instance.
* @param gender Can any of {@link #GENDER_NEUTRAL},
* {@link #GENDER_MALE} and {@link #GENDER_FEMALE}.
* @return This instance.
*/
public C setGender(String gender) {
return setStringArgument(TtsSpan.ARG_GENDER, gender);
}
/**
* Sets the animacy information for this instance.
* @param animacy Can be any of {@link #ANIMACY_ANIMATE} and
* {@link #ANIMACY_INANIMATE}.
* @return This instance.
*/
public C setAnimacy(String animacy) {
return setStringArgument(TtsSpan.ARG_ANIMACY, animacy);
}
/**
* Sets the multiplicity information for this instance.
* @param multiplicity Can be any of
* {@link #MULTIPLICITY_SINGLE}, {@link #MULTIPLICITY_DUAL} and
* {@link #MULTIPLICITY_PLURAL}.
* @return This instance.
*/
public C setMultiplicity(String multiplicity) {
return setStringArgument(TtsSpan.ARG_MULTIPLICITY, multiplicity);
}
/**
* Sets the grammatical case information for this instance.
* @param grammaticalCase Can be any of {@link #CASE_NOMINATIVE},
* {@link #CASE_ACCUSATIVE}, {@link #CASE_DATIVE},
* {@link #CASE_ABLATIVE}, {@link #CASE_GENITIVE},
* {@link #CASE_VOCATIVE}, {@link #CASE_LOCATIVE} and
* {@link #CASE_INSTRUMENTAL}.
* @return This instance.
*/
public C setCase(String grammaticalCase) {
return setStringArgument(TtsSpan.ARG_CASE, grammaticalCase);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_TEXT}.
*/
public static class TextBuilder extends SemioticClassBuilder<TextBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_TEXT}.
*/
public TextBuilder() {
super(TtsSpan.TYPE_TEXT);
}
/**
* Creates a TtsSpan of type {@link #TYPE_TEXT} and sets the
* {@link #ARG_TEXT} argument.
* @param text The text to be synthesized.
* @see #setText(String)
*/
public TextBuilder(String text) {
this();
setText(text);
}
/**
* Sets the {@link #ARG_TEXT} argument, the text to be synthesized.
* @param text The string that will be synthesized.
* @return This instance.
*/
public TextBuilder setText(String text) {
return setStringArgument(TtsSpan.ARG_TEXT, text);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_CARDINAL}.
*/
public static class CardinalBuilder
extends SemioticClassBuilder<CardinalBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_CARDINAL}.
*/
public CardinalBuilder() {
super(TtsSpan.TYPE_CARDINAL);
}
/**
* Creates a TtsSpan of type {@link #TYPE_CARDINAL} and sets the
* {@link #ARG_NUMBER} argument.
* @param number The number to synthesize.
* @see #setNumber(long)
*/
public CardinalBuilder(long number) {
this();
setNumber(number);
}
/**
* Creates a TtsSpan of type {@link #TYPE_CARDINAL} and sets the
* {@link #ARG_NUMBER} argument.
* @param number The number to synthesize.
* @see #setNumber(String)
*/
public CardinalBuilder(String number) {
this();
setNumber(number);
}
/**
* Convenience method that converts the number to a String and set it to
* the value for {@link #ARG_NUMBER}.
* @param number The number that will be synthesized.
* @return This instance.
*/
public CardinalBuilder setNumber(long number) {
return setNumber(String.valueOf(number));
}
/**
* Sets the {@link #ARG_NUMBER} argument.
* @param number A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public CardinalBuilder setNumber(String number) {
return setStringArgument(TtsSpan.ARG_NUMBER, number);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_ORDINAL}.
*/
public static class OrdinalBuilder
extends SemioticClassBuilder<OrdinalBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_ORDINAL}.
*/
public OrdinalBuilder() {
super(TtsSpan.TYPE_ORDINAL);
}
/**
* Creates a TtsSpan of type {@link #TYPE_ORDINAL} and sets the
* {@link #ARG_NUMBER} argument.
* @param number The ordinal number to synthesize.
* @see #setNumber(long)
*/
public OrdinalBuilder(long number) {
this();
setNumber(number);
}
/**
* Creates a TtsSpan of type {@link #TYPE_ORDINAL} and sets the
* {@link #ARG_NUMBER} argument.
* @param number The number to synthesize.
* @see #setNumber(String)
*/
public OrdinalBuilder(String number) {
this();
setNumber(number);
}
/**
* Convenience method that converts the number to a String and sets it
* to the value for {@link #ARG_NUMBER}.
* @param number The ordinal number that will be synthesized.
* @return This instance.
*/
public OrdinalBuilder setNumber(long number) {
return setNumber(String.valueOf(number));
}
/**
* Sets the {@link #ARG_NUMBER} argument.
* @param number A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public OrdinalBuilder setNumber(String number) {
return setStringArgument(TtsSpan.ARG_NUMBER, number);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_DECIMAL}.
*/
public static class DecimalBuilder
extends SemioticClassBuilder<DecimalBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_DECIMAL}.
*/
public DecimalBuilder() {
super(TtsSpan.TYPE_DECIMAL);
}
/**
* Creates a TtsSpan of type {@link #TYPE_DECIMAL} and sets the
* {@link #ARG_INTEGER_PART} and {@link #ARG_FRACTIONAL_PART} arguments.
* @see {@link #setArgumentsFromDouble(double, int, int)
*/
public DecimalBuilder(double number,
int minimumFractionDigits,
int maximumFractionDigits) {
this();
setArgumentsFromDouble(number,
minimumFractionDigits,
maximumFractionDigits);
}
/**
* Creates a TtsSpan of type {@link #TYPE_DECIMAL} and sets the
* {@link #ARG_INTEGER_PART} and {@link #ARG_FRACTIONAL_PART} arguments.
*/
public DecimalBuilder(String integerPart, String fractionalPart) {
this();
setIntegerPart(integerPart);
setFractionalPart(fractionalPart);
}
/**
* Convenience method takes a double and a maximum number of fractional
* digits, it sets the {@link #ARG_INTEGER_PART} and
* {@link #ARG_FRACTIONAL_PART} arguments.
* @param number The number to be synthesized.
* @param minimumFractionDigits The minimum number of fraction digits
* that are pronounced.
* @param maximumFractionDigits The maximum number of fraction digits
* that are pronounced. If maximumFractionDigits <
* minimumFractionDigits then minimumFractionDigits will be assumed
* to be equal to maximumFractionDigits.
* @return This instance.
*/
public DecimalBuilder setArgumentsFromDouble(
double number,
int minimumFractionDigits,
int maximumFractionDigits) {
// Format double.
NumberFormat formatter = NumberFormat.getInstance(Locale.US);
formatter.setMinimumFractionDigits(maximumFractionDigits);
formatter.setMaximumFractionDigits(maximumFractionDigits);
formatter.setGroupingUsed(false);
String str = formatter.format(number);
// Split at decimal point.
int i = str.indexOf('.');
if (i >= 0) {
setIntegerPart(str.substring(0, i));
setFractionalPart(str.substring(i + 1));
} else {
setIntegerPart(str);
}
return this;
}
/**
* Convenience method that converts the number to a String and sets it
* to the value for {@link #ARG_INTEGER_PART}.
* @param integerPart The integer part of the decimal.
* @return This instance.
*/
public DecimalBuilder setIntegerPart(long integerPart) {
return setIntegerPart(String.valueOf(integerPart));
}
/**
* Sets the {@link #ARG_INTEGER_PART} argument.
* @param integerPart A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public DecimalBuilder setIntegerPart(String integerPart) {
return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
}
/**
* Sets the {@link #ARG_FRACTIONAL_PART} argument.
* @param fractionalPart A non-empty string of digits.
* @return This instance.
*/
public DecimalBuilder setFractionalPart(String fractionalPart) {
return setStringArgument(TtsSpan.ARG_FRACTIONAL_PART,
fractionalPart);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_FRACTION}.
*/
public static class FractionBuilder
extends SemioticClassBuilder<FractionBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_FRACTION}.
*/
public FractionBuilder() {
super(TtsSpan.TYPE_FRACTION);
}
/**
* Creates a TtsSpan of type {@link #TYPE_FRACTION} and sets the
* {@link #ARG_INTEGER_PART}, {@link #ARG_NUMERATOR}, and
* {@link #ARG_DENOMINATOR} arguments.
*/
public FractionBuilder(long integerPart,
long numerator,
long denominator) {
this();
setIntegerPart(integerPart);
setNumerator(numerator);
setDenominator(denominator);
}
/**
* Convenience method that converts the integer to a String and sets the
* argument {@link #ARG_NUMBER}.
* @param integerPart The integer part.
* @return This instance.
*/
public FractionBuilder setIntegerPart(long integerPart) {
return setIntegerPart(String.valueOf(integerPart));
}
/**
* Sets the {@link #ARG_INTEGER_PART} argument.
* @param integerPart A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public FractionBuilder setIntegerPart(String integerPart) {
return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
}
/**
* Convenience method that converts the numerator to a String and sets
* the argument {@link #ARG_NUMERATOR}.
* @param numerator The numerator.
* @return This instance.
*/
public FractionBuilder setNumerator(long numerator) {
return setNumerator(String.valueOf(numerator));
}
/**
* Sets the {@link #ARG_NUMERATOR} argument.
* @param numerator A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public FractionBuilder setNumerator(String numerator) {
return setStringArgument(TtsSpan.ARG_NUMERATOR, numerator);
}
/**
* Convenience method that converts the denominator to a String and sets
* the argument {@link #ARG_DENOMINATOR}.
* @param denominator The denominator.
* @return This instance.
*/
public FractionBuilder setDenominator(long denominator) {
return setDenominator(String.valueOf(denominator));
}
/**
* Sets the {@link #ARG_DENOMINATOR} argument.
* @param denominator A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public FractionBuilder setDenominator(String denominator) {
return setStringArgument(TtsSpan.ARG_DENOMINATOR, denominator);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_MEASURE}.
*/
public static class MeasureBuilder
extends SemioticClassBuilder<MeasureBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_MEASURE}.
*/
public MeasureBuilder() {
super(TtsSpan.TYPE_MEASURE);
}
/**
* Convenience method that converts the number to a String and set it to
* the value for {@link #ARG_NUMBER}.
* @param number The amount of the measure.
* @return This instance.
*/
public MeasureBuilder setNumber(long number) {
return setNumber(String.valueOf(number));
}
/**
* Sets the {@link #ARG_NUMBER} argument.
* @param number A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public MeasureBuilder setNumber(String number) {
return setStringArgument(TtsSpan.ARG_NUMBER, number);
}
/**
* Convenience method that converts the integer part to a String and set
* it to the value for {@link #ARG_INTEGER_PART}.
* @param integerPart The integer part of a decimal or fraction.
* @return This instance.
*/
public MeasureBuilder setIntegerPart(long integerPart) {
return setNumber(String.valueOf(integerPart));
}
/**
* Sets the {@link #ARG_INTEGER_PART} argument.
* @param integerPart The integer part of a decimal or fraction; a
* non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public MeasureBuilder setIntegerPart(String integerPart) {
return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
}
/**
* Sets the {@link #ARG_FRACTIONAL_PART} argument.
* @param fractionalPart The fractional part of a decimal; a non-empty
* string of digits with an optional leading + or -.
* @return This instance.
*/
public MeasureBuilder setFractionalPart(String fractionalPart) {
return setStringArgument(TtsSpan.ARG_FRACTIONAL_PART,
fractionalPart);
}
/**
* Convenience method that converts the numerator to a String and set it
* to the value for {@link #ARG_NUMERATOR}.
* @param numerator The numerator of a fraction.
* @return This instance.
*/
public MeasureBuilder setNumerator(long numerator) {
return setNumerator(String.valueOf(numerator));
}
/**
* Sets the {@link #ARG_NUMERATOR} argument.
* @param numerator The numerator of a fraction; a non-empty string of
* digits with an optional leading + or -.
* @return This instance.
*/
public MeasureBuilder setNumerator(String numerator) {
return setStringArgument(TtsSpan.ARG_NUMERATOR, numerator);
}
/**
* Convenience method that converts the denominator to a String and set
* it to the value for {@link #ARG_DENOMINATOR}.
* @param denominator The denominator of a fraction.
* @return This instance.
*/
public MeasureBuilder setDenominator(long denominator) {
return setDenominator(String.valueOf(denominator));
}
/**
* Sets the {@link #ARG_DENOMINATOR} argument.
* @param denominator The denominator of a fraction; a non-empty string
* of digits with an optional leading + or -.
* @return This instance.
*/
public MeasureBuilder setDenominator(String denominator) {
return setStringArgument(TtsSpan.ARG_DENOMINATOR, denominator);
}
/**
* Sets the {@link #ARG_UNIT} argument.
* @param unit The unit of the measure.
* @return This instance.
* @see {@link TtsSpan.ARG_UNIT}
*/
public MeasureBuilder setUnit(String unit) {
return setStringArgument(TtsSpan.ARG_UNIT, unit);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_TIME}.
*/
public static class TimeBuilder
extends SemioticClassBuilder<TimeBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_TIME}.
*/
public TimeBuilder() {
super(TtsSpan.TYPE_TIME);
}
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_TIME} and
* sets the {@link #ARG_HOURS} and {@link #ARG_MINUTES} arguments.
*/
public TimeBuilder(int hours, int minutes) {
this();
setHours(hours);
setMinutes(minutes);
}
/**
* Sets the {@link #ARG_HOURS} argument.
* @param hours The value to be set for hours. See {@link #ARG_HOURS}.
* @return This instance.
* @see {@link #ARG_HOURS}
*/
public TimeBuilder setHours(int hours) {
return setIntArgument(TtsSpan.ARG_HOURS, hours);
}
/**
* Sets the {@link #ARG_MINUTES} argument.
* @param minutes The value to be set for minutes. See
* {@link #ARG_MINUTES}.
* @return This instance.
* @see {@link #ARG_MINUTES}
*/
public TimeBuilder setMinutes(int minutes) {
return setIntArgument(TtsSpan.ARG_MINUTES, minutes);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_DATE}.
*/
public static class DateBuilder
extends SemioticClassBuilder<DateBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_DATE}.
*/
public DateBuilder() {
super(TtsSpan.TYPE_DATE);
}
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_TIME} and
* possibly sets the {@link #ARG_WEEKDAY}, {@link #ARG_DAY},
* {@link #ARG_MONTH} and {@link #ARG_YEAR} arguments. Pass null to any
* argument to leave it unset.
*/
public DateBuilder(Integer weekday,
Integer day,
Integer month,
Integer year) {
this();
if (weekday != null) {
setWeekday(weekday);
}
if (day != null) {
setDay(day);
}
if (month != null) {
setMonth(month);
}
if (year != null) {
setYear(year);
}
}
/**
* Sets the {@link #ARG_WEEKDAY} argument.
* @param weekday The value to be set for weekday. See
* {@link #ARG_WEEKDAY}.
* @return This instance.
* @see {@link #ARG_WEEKDAY}
*/
public DateBuilder setWeekday(int weekday) {
return setIntArgument(TtsSpan.ARG_WEEKDAY, weekday);
}
/**
* Sets the {@link #ARG_DAY} argument.
* @param day The value to be set for day. See {@link #ARG_DAY}.
* @return This instance.
* @see {@link #ARG_DAY}
*/
public DateBuilder setDay(int day) {
return setIntArgument(TtsSpan.ARG_DAY, day);
}
/**
* Sets the {@link #ARG_MONTH} argument.
* @param month The value to be set for month. See {@link #ARG_MONTH}.
* @return This instance.
* @see {@link #ARG_MONTH}
*/
public DateBuilder setMonth(int month) {
return setIntArgument(TtsSpan.ARG_MONTH, month);
}
/**
* Sets the {@link #ARG_YEAR} argument.
* @param year The value to be set for year. See {@link #ARG_YEAR}.
* @return This instance.
* @see {@link #ARG_YEAR}
*/
public DateBuilder setYear(int year) {
return setIntArgument(TtsSpan.ARG_YEAR, year);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_MONEY}.
*/
public static class MoneyBuilder
extends SemioticClassBuilder<MoneyBuilder> {
/**
* Creates a TtsSpan of type {@link #TYPE_MONEY}.
*/
public MoneyBuilder() {
super(TtsSpan.TYPE_MONEY);
}
/**
* Convenience method that converts the number to a String and set it to
* the value for {@link #ARG_INTEGER_PART}.
* @param integerPart The integer part of the amount.
* @return This instance.
*/
public MoneyBuilder setIntegerPart(long integerPart) {
return setIntegerPart(String.valueOf(integerPart));
}
/**
* Sets the {@link #ARG_INTEGER_PART} argument.
* @param integerPart A non-empty string of digits with an optional
* leading + or -.
* @return This instance.
*/
public MoneyBuilder setIntegerPart(String integerPart) {
return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
}
/**
* Sets the {@link #ARG_FRACTIONAL_PART} argument.
* @param fractionalPart Can be a string of digits of any size.
* @return This instance.
*/
public MoneyBuilder setFractionalPart(String fractionalPart) {
return setStringArgument(TtsSpan.ARG_FRACTIONAL_PART, fractionalPart);
}
/**
* Sets the {@link #ARG_CURRENCY} argument.
* @param currency Should be a ISO4217 currency code, e.g. "USD".
* @return This instance.
*/
public MoneyBuilder setCurrency(String currency) {
return setStringArgument(TtsSpan.ARG_CURRENCY, currency);
}
/**
* Sets the {@link #ARG_QUANTITY} argument.
* @param quantity
* @return This instance.
*/
public MoneyBuilder setQuantity(String quantity) {
return setStringArgument(TtsSpan.ARG_QUANTITY, quantity);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_TELEPHONE}.
*/
public static class TelephoneBuilder
extends SemioticClassBuilder<TelephoneBuilder> {
/**
* Creates a TtsSpan of type {@link #TYPE_TELEPHONE}.
*/
public TelephoneBuilder() {
super(TtsSpan.TYPE_TELEPHONE);
}
/**
* Creates a TtsSpan of type {@link #TYPE_TELEPHONE} and sets the
* {@link #ARG_NUMBER_PARTS} argument.
*/
public TelephoneBuilder(String numberParts) {
this();
setNumberParts(numberParts);
}
/**
* Sets the {@link #ARG_COUNTRY_CODE} argument.
* @param countryCode The country code can be a series of digits
* optionally prefixed with a "+".
* @return This instance.
*/
public TelephoneBuilder setCountryCode(String countryCode) {
return setStringArgument(TtsSpan.ARG_COUNTRY_CODE, countryCode);
}
/**
* Sets the {@link #ARG_NUMBER_PARTS} argument.
* @param numberParts The main telephone number. Can be a series of
* digits and letters separated by spaces, "/", "-" or ".".
* @return This instance.
*/
public TelephoneBuilder setNumberParts(String numberParts) {
return setStringArgument(TtsSpan.ARG_NUMBER_PARTS, numberParts);
}
/**
* Sets the {@link #ARG_EXTENSION} argument.
* @param extension The extension can be a series of digits.
* @return This instance.
*/
public TelephoneBuilder setExtension(String extension) {
return setStringArgument(TtsSpan.ARG_EXTENSION, extension);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_ELECTRONIC}.
*/
public static class ElectronicBuilder
extends SemioticClassBuilder<ElectronicBuilder> {
/**
* Creates a TtsSpan of type {@link #TYPE_ELECTRONIC}.
*/
public ElectronicBuilder() {
super(TtsSpan.TYPE_ELECTRONIC);
}
/**
* Sets the {@link #ARG_USERNAME} and {@link #ARG_DOMAIN}
* arguments, representing an email address.
* @param username The part before the @ in the email address.
* @param domain The part after the @ in the email address.
* @return This instance.
*/
public ElectronicBuilder setEmailArguments(String username,
String domain) {
return setDomain(domain).setUsername(username);
}
/**
* Sets the {@link #ARG_PROTOCOL} argument.
* @param protocol The protocol of the URI. Examples are "http" and
* "ftp".
* @return This instance.
*/
public ElectronicBuilder setProtocol(String protocol) {
return setStringArgument(TtsSpan.ARG_PROTOCOL, protocol);
}
/**
* Sets the {@link #ARG_USERNAME} argument.
* @return This instance.
*/
public ElectronicBuilder setUsername(String username) {
return setStringArgument(TtsSpan.ARG_USERNAME, username);
}
/**
* Sets the {@link #ARG_PASSWORD} argument.
* @return This instance.
*/
public ElectronicBuilder setPassword(String password) {
return setStringArgument(TtsSpan.ARG_PASSWORD, password);
}
/**
* Sets the {@link #ARG_DOMAIN} argument.
* @param domain The domain, for example "source.android.com".
* @return This instance.
*/
public ElectronicBuilder setDomain(String domain) {
return setStringArgument(TtsSpan.ARG_DOMAIN, domain);
}
/**
* Sets the {@link #ARG_PORT} argument.
* @return This instance.
*/
public ElectronicBuilder setPort(int port) {
return setIntArgument(TtsSpan.ARG_PORT, port);
}
/**
* Sets the {@link #ARG_PATH} argument.
* @param path For example "source/index.html".
* @return This instance.
*/
public ElectronicBuilder setPath(String path) {
return setStringArgument(TtsSpan.ARG_PATH, path);
}
/**
* Sets the {@link #ARG_QUERY_STRING} argument.
* @param queryString For example "arg=value&argtwo=value".
* @return This instance.
*/
public ElectronicBuilder setQueryString(String queryString) {
return setStringArgument(TtsSpan.ARG_QUERY_STRING, queryString);
}
/**
* Sets the {@link #ARG_FRAGMENT_ID} argument.
* @return This instance.
*/
public ElectronicBuilder setFragmentId(String fragmentId) {
return setStringArgument(TtsSpan.ARG_FRAGMENT_ID, fragmentId);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_DIGITS}.
*/
public static class DigitsBuilder
extends SemioticClassBuilder<DigitsBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_DIGITS}.
*/
public DigitsBuilder() {
super(TtsSpan.TYPE_DIGITS);
}
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_DIGITS}
* and sets the {@link #ARG_DIGITS} argument.
*/
public DigitsBuilder(String digits) {
this();
setDigits(digits);
}
/**
* Sets the {@link #ARG_DIGITS} argument.
* @param digits A string of digits.
* @return This instance.
*/
public DigitsBuilder setDigits(String digits) {
return setStringArgument(TtsSpan.ARG_DIGITS, digits);
}
}
/**
* A builder for TtsSpans of type {@link #TYPE_VERBATIM}.
*/
public static class VerbatimBuilder
extends SemioticClassBuilder<VerbatimBuilder> {
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_VERBATIM}.
*/
public VerbatimBuilder() {
super(TtsSpan.TYPE_VERBATIM);
}
/**
* Creates a builder for a TtsSpan of type {@link #TYPE_VERBATIM}
* and sets the {@link #ARG_VERBATIM} argument.
*/
public VerbatimBuilder(String verbatim) {
this();
setVerbatim(verbatim);
}
/**
* Sets the {@link #ARG_VERBATIM} argument.
* @param verbatim A string of characters that will be read verbatim,
* except whitespace.
* @return This instance.
*/
public VerbatimBuilder setVerbatim(String verbatim) {
return setStringArgument(TtsSpan.ARG_VERBATIM, verbatim);
}
}
}