Merge "Add documents for the spell checker framework and the input method subtype" into ics-mr0

 * SpellCheckerService provides an abstract base class for a spell checker.

 * This class combines a service to the system with the spell checker service interface that

 * spell checker must implement.

 *

 * <p>In addition to the normal Service lifecycle methods, this class

 * introduces a new specific callback that subclasses should override

 * {@link #createSession()} to provide a spell checker session that is corresponding

 * to requested language and so on. The spell checker session returned by this method

 * should extend {@link SpellCheckerService.Session}.

 * </p>

 *

 * <h3>Returning spell check results</h3>

 *

 * <p>{@link SpellCheckerService.Session#onGetSuggestions(TextInfo, int)}

 * should return spell check results.

 * It receives {@link android.view.textservice.TextInfo} and returns

 * {@link android.view.textservice.SuggestionsInfo} for the input.

 * You may want to override

 * {@link SpellCheckerService.Session#onGetSuggestionsMultiple(TextInfo[], int, boolean)} for

 * better performance and quality.

 * </p>

 *

 * <p>Please note that {@link SpellCheckerService.Session#getLocale()} does not return a valid

 * locale before {@link SpellCheckerService.Session#onCreate()} </p>

 *

 */

public abstract class SpellCheckerService extends Service {

    private static final String TAG = SpellCheckerService.class.getSimpleName();

         * but will be called in series on another thread.

         * @param textInfo the text metadata

         * @param suggestionsLimit the number of limit of suggestions returned

         * @return SuggestionInfo which contains suggestions for textInfo

         * @return SuggestionsInfo which contains suggestions for textInfo

         */

        public abstract SuggestionsInfo onGetSuggestions(TextInfo textInfo, int suggestionsLimit);

         * @param textInfos an array of the text metadata

         * @param suggestionsLimit the number of limit of suggestions returned

         * @param sequentialWords true if textInfos can be treated as sequential words.

         * @return an array of SuggestionInfo of onGetSuggestions

         * @return an array of SuggestionsInfo of onGetSuggestions

         */

        public SuggestionsInfo[] onGetSuggestionsMultiple(TextInfo[] textInfos,

                int suggestionsLimit, boolean sequentialWords) {

 * Subtype can describe locale (e.g. en_US, fr_FR...) and mode (e.g. voice, keyboard...), and is

 * used for IME switch and settings. The input method subtype allows the system to bring up the

 * specified subtype of the designated input method directly.

 *

 * <p>It should be defined in an XML resource file of the input method

 * with the <code>&lt;subtype></code> element.

 * For more information, see the guide to

 * <a href="{@docRoot}resources/articles/creating-input-method.html">

 * Creating an Input Method</a>.</p>

 *

 */

public final class InputMethodSubtype implements Parcelable {

    private static final String TAG = InputMethodSubtype.class.getSimpleName();

/**

 * The SpellCheckerSession interface provides the per client functionality of SpellCheckerService.

 *

 *

 * <a name="Applications"></a>

 * <h3>Applications</h3>

 *

 * <p>In most cases, applications that are using the standard

 * {@link android.widget.TextView} or its subclasses will have little they need

 * to do to work well with spell checker services.  The main things you need to

 * be aware of are:</p>

 *

 * <ul>

 * <li> Properly set the {@link android.R.attr#inputType} in your editable

 * text views, so that the spell checker will have enough context to help the

 * user in editing text in them.

 * </ul>

 *

 * <p>For the rare people amongst us writing client applications that use the spell checker service

 * directly, you will need to use {@link #getSuggestions(TextInfo, int)} or

 * {@link #getSuggestions(TextInfo[], int, boolean)} for obtaining results from the spell checker

 * service by yourself.</p>

 *

 * <h3>Security</h3>

 *

 * <p>There are a lot of security issues associated with spell checkers,

 * since they could monitor all the text being sent to them

 * through, for instance, {@link android.widget.TextView}.

 * The Android spell checker framework also allows

 * arbitrary third party spell checkers, so care must be taken to restrict their

 * selection and interactions.</p>

 *

 * <p>Here are some key points about the security architecture behind the

 * spell checker framework:</p>

 *

 * <ul>

 * <li>Only the system is allowed to directly access a spell checker framework's

 * {@link android.service.textservice.SpellCheckerService} interface, via the

 * {@link android.Manifest.permission#BIND_TEXT_SERVICE} permission.  This is

 * enforced in the system by not binding to a spell checker service that does

 * not require this permission.

 *

 * <li>The user must explicitly enable a new spell checker in settings before

 * they can be enabled, to confirm with the system that they know about it

 * and want to make it available for use.

 * </ul>

 *

 */

public class SpellCheckerSession {

    private static final String TAG = SpellCheckerSession.class.getSimpleName();

 *

 * The user can change the current text services in Settings. And also applications can specify

 * the target text services.

 *

 * <h3>Architecture Overview</h3>

 *

 * <p>There are three primary parties involved in the text services

 * framework (TSF) architecture:</p>

 *

 * <ul>

 * <li> The <strong>text services manager</strong> as expressed by this class

 * is the central point of the system that manages interaction between all

 * other parts.  It is expressed as the client-side API here which exists

 * in each application context and communicates with a global system service

 * that manages the interaction across all processes.

 * <li> A <strong>text service</strong> implements a particular

 * interaction model allowing the client application to retrieve information of text.

 * The system binds to the current text service that is in use, causing it to be created and run.

 * <li> Multiple <strong>client applications</strong> arbitrate with the text service

 * manager for connections to text services.

 * </ul>

 *

 * <h3>Text services sessions</h3>

 * <ul>

 * <li>The <strong>spell checker session</strong> is one of the text services.

 * {@link android.view.textservice.SpellCheckerSession}</li>

 * </ul>

 *

 */

public final class TextServicesManager {

    private static final String TAG = TextServicesManager.class.getSimpleName();