TtsSpan.java revision 2e3f2c6727d92aa8127ff5adb83facc9d53a2b57 
1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.text.style;
18
19import android.os.Parcel;
20import android.os.PersistableBundle;
21import android.text.ParcelableSpan;
22import android.text.TextUtils;
23
24/**
25 * A span that supplies additional meta-data intended for text-to-speech rendering
26 * of the associated text.  If the text is being processed by a text-to-speech
27 * engine, the engine may use the data in this span in addition to or instead of
28 * its associated text.
29 */
30public class TtsSpan implements ParcelableSpan {
31    private final String mType;
32    private final PersistableBundle mArgs;
33
34    /**
35     * This span type can be used to add morphosyntactic features to the text it
36     * spans over, or synthesize a something else than the spanned text.  Use
37     * the argument {@link #ARG_TEXT} to set a different text.
38     * Accepts the arguments {@link #ARG_GENDER},
39     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
40     * {@link #ARG_CASE}.
41     */
42    public static final String TYPE_TEXT = "android.type.text";
43
44    /**
45     * The text associated with this span is a cardinal.  Must include the
46     * number to be synthesized with {@link #ARG_NUMBER}.
47     * Also accepts the arguments {@link #ARG_GENDER},
48     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
49     * {@link #ARG_CASE}.
50     */
51    public static final String TYPE_CARDINAL = "android.type.cardinal";
52
53    /**
54     * The text associated with this span is an ordinal. Must include the
55     * number to be synthesized with {@link #ARG_NUMBER}.
56     * Also accepts the arguments {@link #ARG_GENDER},
57     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
58     * {@link #ARG_CASE}.
59     */
60    public static final String TYPE_ORDINAL = "android.type.ordinal";
61
62    /**
63     * The text associated with this span is a decimal number. Must include the
64     * number to be synthesized with {@link #ARG_INTEGER_PART} and
65     * {@link #ARG_FRACTIONAL_PART}.
66     * Also accepts the arguments {@link #ARG_GENDER},
67     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
68     * {@link #ARG_CASE}.
69     */
70    public static final String TYPE_DECIMAL = "android.type.decimal";
71
72    /**
73     * The text associated with this span is a fractional number. Must include
74     * the number to be synthesized with {@link #ARG_NUMERATOR} and
75     * {@link #ARG_DENOMINATOR}. {@link #ARG_INTEGER_PART} is optional
76     * Also accepts the arguments {@link #ARG_GENDER},
77     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
78     * {@link #ARG_CASE}.
79     */
80    public static final String TYPE_FRACTION = "android.type.fraction";
81
82    /**
83     * The text associated with this span is a measure, consisting of a number
84     * and a unit. The number can be a cardinal, decimal or a fraction. Set the
85     * number with the same arguments as {@link #TYPE_CARDINAL},
86     * {@link #TYPE_DECIMAL} or {@link #TYPE_FRACTION}. The unit can be
87     * specified with {@link #ARG_UNIT}.
88     * Also accepts the arguments {@link #ARG_GENDER},
89     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
90     * {@link #ARG_CASE}.
91     */
92    public static final String TYPE_MEASURE = "android.type.measure";
93
94    /**
95     * The text associated with this span is a time, consisting of a number of
96     * hours and minutes, specified with {@link #ARG_HOURS} and
97     * {@link #ARG_MINUTES}.
98     * Also accepts the arguments {@link #ARG_GENDER},
99     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
100     * {@link #ARG_CASE}.
101     */
102    public static final String TYPE_TIME = "android.type.time";
103
104    /**
105     * The text associated with this span is a date. All arguments are optional,
106     * but at least one has to be provided: {@link #ARG_WEEKDAY},
107     * {@link #ARG_DAY}, {@link #ARG_MONTH} and {@link #ARG_YEAR}.
108     * Also accepts the arguments {@link #ARG_GENDER},
109     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
110     * {@link #ARG_CASE}.
111     */
112    public static final String TYPE_DATE = "android.type.date";
113
114    /**
115     * The text associated with this span is a telephone number. The argument
116     * {@link #ARG_NUMBER_PART} is required. {@link #ARG_COUNTRY_CODE} and
117     * {@link #ARG_EXTENSION} are optional.
118     * Also accepts the arguments {@link #ARG_GENDER},
119     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
120     * {@link #ARG_CASE}.
121     */
122    public static final String TYPE_TELEPHONE = "android.type.telephone";
123
124
125    /**
126     * The text associated with this span is a URI (can be used for URLs and
127     * email addresses). The full schema for URLs, which email addresses can
128     * effectively be seen as a subset of, is:
129     * protocol://username:password@domain:port/path?query_string#fragment_id
130     * Hence populating just username and domain will read as an email address.
131     * All arguments are optional, but at least one has to be provided:
132     * {@link #ARG_PROTOCOL}, {@link #ARG_USERNAME}, {@link #ARG_PASSWORD},
133     * {@link #ARG_DOMAIN}, {@link #ARG_PORT}, {@link #ARG_PATH},
134     * {@link #ARG_QUERY_STRING} and {@link #ARG_FRAGMENT_ID}.
135     * Also accepts the arguments {@link #ARG_GENDER},
136     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
137     * {@link #ARG_CASE}.
138     */
139    public static final String TYPE_ELECTRONIC = "android.type.electronic";
140
141    /**
142     * The text associated with this span is a series of digits that have to be
143     * read sequentially. {@link #ARG_DIGITS} is required.
144     * Also accepts the arguments {@link #ARG_GENDER},
145     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
146     * {@link #ARG_CASE}.
147     */
148    public static final String TYPE_DIGITS = "android.type.digits";
149
150    /**
151     * The text associated with this span is a series of characters that have to
152     * be read verbatim. The engine will attempt to ready out any character like
153     * punctuation but excluding whitespace. {@link #ARG_VERBATIM} is required.
154     * Also accepts the arguments {@link #ARG_GENDER},
155     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
156     * {@link #ARG_CASE}.
157     */
158    public static final String TYPE_VERBATIM = "android.type.verbatim";
159
160    /**
161     * String argument supplying gender information.  Can be any of
162     * {@link #GENDER_NEUTRAL}, {@link #GENDER_MALE} and
163     * {@link #GENDER_FEMALE}.
164     */
165    public static final String ARG_GENDER = "android.arg.gender";
166
167    public static final String GENDER_NEUTRAL = "android.neutral";
168    public static final String GENDER_MALE = "android.male";
169    public static final String GENDER_FEMALE = "android.female";
170
171    /**
172     * String argument supplying animacy information.  Can be
173     * {@link #ANIMACY_ANIMATE} or
174     * {@link #ANIMACY_INANIMATE}
175     */
176    public static final String ARG_ANIMACY = "android.arg.animacy";
177
178    public static final String ANIMACY_ANIMATE = "android.animate";
179    public static final String ANIMACY_INANIMATE = "android.inanimate";
180
181    /**
182     * String argument supplying multiplicity information.  Can be any of
183     * {@link #MULTIPLICITY_SINGLE},
184     * {@link #MULTIPLICITY_DUAL} and
185     * {@link #MULTIPLICITY_PLURAL}
186     */
187    public static final String ARG_MULTIPLICITY = "android.arg.multiplicity";
188
189    public static final String MULTIPLICITY_SINGLE = "android.single";
190    public static final String MULTIPLICITY_DUAL = "android.dual";
191    public static final String MULTIPLICITY_PLURAL = "android.plural";
192
193    /**
194     * String argument supplying case information.  Can be any of
195     * {@link #CASE_NOMINATIVE}, {@link #CASE_ACCUSATIVE},
196     * {@link #CASE_DATIVE}, {@link #CASE_ABLATIVE},
197     * {@link #CASE_GENITIVE}, {@link #CASE_VOCATIVE},
198     * {@link #CASE_LOCATIVE} and
199     * {@link #CASE_INSTRUMENTAL}
200     */
201    public static final String ARG_CASE = "android.arg.case";
202
203    public static final String CASE_NOMINATIVE = "android.nomative";
204    public static final String CASE_ACCUSATIVE = "android.accusative";
205    public static final String CASE_DATIVE = "android.dative";
206    public static final String CASE_ABLATIVE = "android.ablative";
207    public static final String CASE_GENITIVE = "android.genitive";
208    public static final String CASE_VOCATIVE = "android.vocative";
209    public static final String CASE_LOCATIVE = "android.locative";
210    public static final String CASE_INSTRUMENTAL = "android.instrumental";
211
212    /**
213     * String supplying the text to be synthesized.  The synthesizer is free
214     * to decide how to interpret the text.
215     * Can be used with {@link #TYPE_TEXT}.
216     */
217    public static final String ARG_TEXT = "android.arg.text";
218
219    /**
220     * Argument used to specify a whole number.  The value can be a string of
221     * digits of any size optionally prefixed with a - or +.
222     * Can be used with {@link #TYPE_CARDINAL} and {@link #TYPE_ORDINAL}.
223     */
224    public static final String ARG_NUMBER = "android.arg.number";
225
226    /**
227     * Argument used to specify the integer part of a decimal or fraction. The
228     * value can be a string of digits of any size optionally prefixed with a - or +.
229     * Can be used with {@link #TYPE_DECIMAL} and {@link #TYPE_FRACTION}.
230     */
231    public static final String ARG_INTEGER_PART = "android.arg.integer_part";
232
233    /**
234     * Argument used to specify the fractional part of a decimal. The value can
235     * be a string of digits of any size.
236     * Can be used with {@link #TYPE_DECIMAL}.
237     */
238    public static final String ARG_FRACTIONAL_PART =
239        "android.arg.fractional_part";
240
241    /**
242     * Argument used to specify the numerator of a fraction. The value can be a
243     * string of digits of any size optionally prefixed with a - or +.
244     * Can be used with {@link #TYPE_FRACTION}.
245     */
246    public static final String ARG_NUMERATOR = "android.arg.numerator";
247
248    /**
249     * Argument used to specify the denominator of a fraction. The value can be
250     * a string of digits of any size optionally prefixed with a + or -.
251     * Can be used with {@link #TYPE_FRACTION}.
252     */
253    public static final String ARG_DENOMINATOR = "android.arg.denominator";
254
255    /**
256     * Argument used to specify the unit of a measure. The unit should always be
257     * specified in English singular form. Prefixes may be used. Engines will do
258     * their best to pronounce them correctly in the language used. Engines are
259     * expected to at least support the most common ones like 'meter', 'second',
260     * 'degree celcius' and 'degree fahrenheit' with some common prefixes like
261     * 'milli' and 'kilo'.
262     * Can be used with {@link #TYPE_MEASURE}.
263     */
264    public static final String ARG_UNIT = "android.arg.unit";
265
266    /**
267     * Argument used to specify the hours of a time. The hours should be
268     * provided as an integer in the range from 0 up to and including 24.
269     * Can be used with {@link #TYPE_TIME}.
270     */
271    public static final String ARG_HOURS = "android.arg.hours";
272
273    /**
274     * Argument used to specify the minutes of a time. The hours should be
275     * provided as an integer in the range from 0 up to and including 59.
276     * Can be used with {@link #TYPE_TIME}.
277     */
278    public static final String ARG_MINUTES = "android.arg.minutes";
279
280    /**
281     * Argument used to specify the weekday of a date. The value should be
282     * provided as an integer and can be any of {@link #WEEKDAY_SUNDAY},
283     * {@link #WEEKDAY_MONDAY}, {@link #WEEKDAY_TUESDAY},
284     * {@link #WEEKDAY_WEDNESDAY}, {@link #WEEKDAY_THURSDAY},
285     * {@link #WEEKDAY_FRIDAY} and {@link #WEEKDAY_SATURDAY}.
286     * Can be used with {@link #TYPE_DATE}.
287     */
288    public static final String ARG_WEEKDAY = "android.arg.weekday";
289
290    public static final int WEEKDAY_SUNDAY = 1;
291    public static final int WEEKDAY_MONDAY = 2;
292    public static final int WEEKDAY_TUESDAY = 3;
293    public static final int WEEKDAY_WEDNESDAY = 4;
294    public static final int WEEKDAY_THURSDAY = 5;
295    public static final int WEEKDAY_FRIDAY = 6;
296    public static final int WEEKDAY_SATURDAY = 7;
297
298    /**
299     * Argument used to specify the day of the month of a date. The value should
300     * be provided as an integer in the range from 1 up to and including 31.
301     * Can be used with {@link #TYPE_DATE}.
302     */
303    public static final String ARG_DAY = "android.arg.day";
304
305    /**
306     * Argument used to specify the month of a date. The value should be
307     * provided as an integer and can be any of {@link #MONTH_JANUARY},
308     * {@link #MONTH_FEBRUARY},  {@link #MONTH_MARCH}, {@link #MONTH_APRIL}, {@link #MONTH_MAY},
309     * {@link #MONTH_JUNE}, {@link #MONTH_JULY}, {@link #MONTH_AUGUST}, {@link #MONTH_SEPTEMBER},
310     * {@link #MONTH_OCTOBER}, {@link #MONTH_NOVEMBER} and {@link #MONTH_DECEMBER}.
311     * Can be used with {@link #TYPE_DATE}.
312     */
313    public static final String ARG_MONTH = "android.arg.month";
314
315    public static final int MONTH_JANUARY = 0;
316    public static final int MONTH_FEBRUARY = 1;
317    public static final int MONTH_MARCH = 2;
318    public static final int MONTH_APRIL = 3;
319    public static final int MONTH_MAY = 4;
320    public static final int MONTH_JUNE = 5;
321    public static final int MONTH_JULY = 6;
322    public static final int MONTH_AUGUST = 7;
323    public static final int MONTH_SEPTEMBER = 8;
324    public static final int MONTH_OCTOBER = 9;
325    public static final int MONTH_NOVEMBER = 10;
326    public static final int MONTH_DECEMBER = 11;
327
328    /**
329     * Argument used to specify the year of a date. The value should be provided
330     * as a positive integer.
331     * Can be used with {@link #TYPE_DATE}.
332     */
333    public static final String ARG_YEAR = "android.arg.year";
334
335    /**
336     * Argument used to specify the country code of a telephone number. Can be
337     * a string of digits.
338     * Can be used with {@link #TYPE_TELEPHONE}.
339     */
340    public static final String ARG_COUNTRY_CODE = "android.arg.country_code";
341
342    /**
343     * Argument used to specify the main number part of a telephone number. Can
344     * be a string of digits.
345     * Can be used with {@link #TYPE_TELEPHONE}.
346     */
347    public static final String ARG_NUMBER_PART = "android.arg.number_part";
348
349    /**
350     * Argument used to specify the extension part of a telephone number. Can be
351     * a string of digits.
352     * Can be used with {@link #TYPE_TELEPHONE}.
353     */
354    public static final String ARG_EXTENSION = "android.arg.extension";
355
356    /**
357     * Argument used to specify the protocol of a URI. Examples are 'http' and
358     * 'ftp'.
359     * Can be used with {@link #TYPE_ELECTRONIC}.
360     */
361    public static final String ARG_PROTOCOL = "android.arg.protocol";
362
363    /**
364     * Argument used to specify the username part of a URI. Should be set as a
365     * string.
366     * Can be used with {@link #TYPE_ELECTRONIC}.
367     */
368    public static final String ARG_USERNAME = "android.arg.username";
369
370    /**
371     * Argument used to specify the password part of a URI. Should be set as a
372     * string.
373     * Can be used with {@link #TYPE_ELECTRONIC}.
374     */
375    public static final String ARG_PASSWORD = "android.arg.password";
376
377    /**
378     * Argument used to specify the domain part of a URI. For example are
379     * 'source.android.com'.
380     * Can be used with {@link #TYPE_ELECTRONIC}.
381     */
382    public static final String ARG_DOMAIN = "android.arg.domain";
383
384    /**
385     * Argument used to specify the port number of a URI. Should be specified as
386     * an integer.
387     * Can be used with {@link #TYPE_ELECTRONIC}.
388     */
389    public static final String ARG_PORT = "android.arg.port";
390
391    /**
392     * Argument used to specify the path part of a URI. For example
393     * 'source/index.html'.
394     * Can be used with {@link #TYPE_ELECTRONIC}.
395     */
396    public static final String ARG_PATH = "android.arg.path";
397
398    /**
399     * Argument used to specify the query string of a URI. For example
400     * 'arg=value&argtwo=value'.
401     * Can be used with {@link #TYPE_ELECTRONIC}.
402     */
403    public static final String ARG_QUERY_STRING = "android.arg.query_string";
404
405    /**
406     * Argument used to specify the fragment id of a URI. Should be specified as
407     * a string.
408     * Can be used with {@link #TYPE_ELECTRONIC}.
409     */
410    public static final String ARG_FRAGMENT_ID = "android.arg.fragment_id";
411
412    /**
413     * Argument used to specify a string of digits.
414     * Can be used with {@link #TYPE_DIGITS}.
415     */
416    public static final String ARG_DIGITS = "android.arg.digits";
417
418    /**
419     * Argument used to specify a string where the characters are read verbatim,
420     * except whitespace.
421     * Can be used with {@link #TYPE_VERBATIM}.
422     */
423    public static final String ARG_VERBATIM = "android.arg.verbatim";
424
425    public TtsSpan(String type, PersistableBundle args) {
426        mType = type;
427        mArgs = args;
428    }
429
430    public TtsSpan(Parcel src) {
431        mType = src.readString();
432        mArgs = src.readPersistableBundle();
433    }
434
435    public String getType() {
436        return mType;
437    }
438
439    public PersistableBundle getArgs() {
440        return mArgs;
441    }
442
443    @Override
444    public int describeContents() {
445        return 0;
446    }
447
448    @Override
449    public void writeToParcel(Parcel dest, int flags) {
450        dest.writeString(mType);
451        dest.writePersistableBundle(mArgs);
452    }
453
454    @Override
455    public int getSpanTypeId() {
456        return TextUtils.TTS_SPAN;
457    }
458}
459