docs/html/guide/topics/text/spell-checker-framework.jd

page.title=Spelling Checker Framework
page.tags=input,spellcheckerservice
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In This Document</h2>
<ol>
    <li>
        <a href="#SpellCheckLifeCycle">Spell Check Lifecycle</a> 
    </li>
    <li>
        <a href="#SpellCheckImplementation">Implementing a Spell Checker Service</a>
    </li>
    <li>
        <a href="#SpellCheckClient">Implementing a Spell Checker Client</a>
    </li>
</ol>
  <h2>See also</h2>
  <ol>
    <li>
        <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html">
        Spell Checker Service</a> sample app
    </li>
    <li>
        <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html">
        Spell Checker Client</a> sample app
    </li>
  </ol>
</div>
</div>

<p>
    The Android platform offers a spelling checker framework that lets you implement   
    and access spell checking in your application. The framework is one of the 
    Text Service APIs offered by the Android platform.
</p>
<p>
    To use the framework in your app, you create a special type of Android service that 
    generates a spelling checker <strong>session</strong> object. Based on text you provide,
    the session object returns spelling suggestions generated by the spelling checker.
</p>
<h2 id="SpellCheckLifeCycle">Spell Checker Lifecycle</h2>
<p>
    The following diagram shows the lifecycle of the spelling checker service:
</p>
<img src="{@docRoot}resources/articles/images/spellcheck_lifecycle.png" alt="" height="596"
    id="figure1" />
<p class="img-caption">
  <strong>Figure 1.</strong> The spelling checker service lifecycle.
</p>
<p>
    To initiate spell checking, your app starts its implementation of the spelling checker
    service. Clients in your app, such as activities or individual UI elements, request a
    spelling checker session from the service, then use the session to get suggestions for text.
    As a client terminates its operation, it closes its spelling checker session. If necessary, your
    app can shut down the spelling checker service at any time.
</p>
<h2 id="SpellCheckImplementation">Implementing a Spell Checker Service</h2>
<p>
    To use the spelling checker framework in your app, add a spelling checker service component including
    the session object definition. You can also add to your app an optional activity that
    controls settings. You must also add an XML metadata file that describes
    the spelling checker service, and add the appropriate elements to your manifest file.
</p>
<h3 id="SpellCheckCode">Spell checker classes</h3>
<p>
    Define the service and session object with the following classes:
</p>
<dl>
    <dt>
        A subclass of {@link android.service.textservice.SpellCheckerService}
    </dt>
    <dd>
        The {@link android.service.textservice.SpellCheckerService} implements both the
        {@link android.app.Service} class and the spelling checker framework interface. Within your
        subclass, you must implement the following method:
        <dl>
            <dt>{@link android.service.textservice.SpellCheckerService#createSession()}</dt>
            <dd>
                A factory method that returns a
                {@link android.service.textservice.SpellCheckerService.Session} object to a
                client that wants to do spell checking.
            </dd>
        </dl>
        <p>
            See the
            <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html">
            Spell Checker Service</a> sample app to learn more about implementing this class.
        </p>
    </dd>
    <dt>
        An implementation of {@link android.service.textservice.SpellCheckerService.Session}
    </dt>
    <dd>
        An object that the spelling checker service provides to clients, to let them pass text to
        the spelling checker and receive suggestions. Within this class, you must implement the
        following methods:
        <dl>
            <dt>
                {@link android.service.textservice.SpellCheckerService.Session#onCreate()}
            </dt>
            <dd>
                Called by the system in response to
                {@link android.service.textservice.SpellCheckerService#createSession()}. In this
                method, you can initialize the
                {@link android.service.textservice.SpellCheckerService.Session} object based on
                the current locale and so forth.
            </dd>
            <dt>
     {@link android.service.textservice.SpellCheckerService.Session#onGetSentenceSuggestionsMultiple(TextInfo[], int)
     onGetSentenceSuggestionsMultiple()}
            </dt>
            <dd>
                Does the actual spell checking. This method returns an array of
                {@link android.view.textservice.SentenceSuggestionsInfo} containing
                suggestions for the sentences passed to it.
            </dd>
        </dl>
        <p>
            Optionally, you can implement
            {@link android.service.textservice.SpellCheckerService.Session#onCancel()}, which
            handles requests to cancel spell checking,
            {@link android.service.textservice.SpellCheckerService.Session#onGetSuggestions(TextInfo, int)
            onGetSuggestions()}, which handles a word suggestion request, or
            {@link android.service.textservice.SpellCheckerService.Session#onGetSuggestionsMultiple(TextInfo[], int, boolean)
            onGetSuggestionsMultiple()}, which handles batches of word suggestion requests.
        </p>
        <p>
            See the
            <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html">
            Spell Checker Client</a> sample app to learn more about implementing this class.
        </p>
    </dd>
</dl>
<p class="note">
    <strong>Note:</strong> You must implement all aspects of spell checking as asynchronous and
    thread-safe. A spelling checker may be called simultaneously by different threads running on
    different cores. The {@link android.service.textservice.SpellCheckerService} and
    {@link android.service.textservice.SpellCheckerService.Session} take care of this
    automatically.
</p>
<h3 id="SpellCheckXML">Spell checker manifest and metadata</h3>
<p>
    In addition to code, you need to provide the appropriate manifest file and a metadata file for
    the spelling checker.
</p>
<p>
    The manifest file defines the application, the service, and the activity for controlling
    settings, as shown in the following snippet:
</p>
<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.android.samplespellcheckerservice" &gt;
    &lt;application
        android:label="&#64;string/app_name" &gt;
        &lt;service
            android:label="&#64;string/app_name"
            android:name=".SampleSpellCheckerService"
            android:permission="android.permission.BIND_TEXT_SERVICE" &gt;
            &lt;intent-filter &gt;
                &lt;action android:name="android.service.textservice.SpellCheckerService" /&gt;
            &lt;/intent-filter&gt;

            &lt;meta-data
                android:name="android.view.textservice.scs"
                android:resource="&#64;xml/spellchecker" /&gt;
        &lt;/service&gt;

        &lt;activity
            android:label="&#64;string/sample_settings"
            android:name="SpellCheckerSettingsActivity" &gt;
            &lt;intent-filter &gt;
                &lt;action android:name="android.intent.action.MAIN" /&gt;
            &lt;/intent-filter&gt;
        &lt;/activity&gt;
    &lt;/application&gt;
&lt;/manifest&gt;
</pre>
<p>
    Notice that components that want to use the service must request the permission
    {@link android.Manifest.permission#BIND_TEXT_SERVICE} to ensure that only the system binds to
    the service. The service's definition also specifies the <code>spellchecker.xml</code> metadata
    file, which is described in the next section.
</p>
<p>
    The metadata file <code>spellchecker.xml</code> contains the following XML:
</p>
<pre>
&lt;spell-checker xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="&#64;string/spellchecker_name"
        android:settingsActivity="com.example.SpellCheckerSettingsActivity"&gt;
    &lt;subtype
            android:label="&#64;string/subtype_generic"
            android:subtypeLocale="en”
    /&gt;
    &lt;subtype
            android:label="&#64;string/subtype_generic"
            android:subtypeLocale="fr”
    /&gt;
&lt;/spell-checker&gt;
</pre>
<p>
    The metadata specifies the activity that the spelling checker uses for controlling settings. It
    also defines subtypes for the spelling checker; in this case, the subtypes define locales that
    the spelling checker can handle.
</p>


<!--  Accessing the Spell Checker Service from a Client -->
<h2 id="SpellCheckClient">Accessing the Spell Checker Service from a Client</h2>
<p>
    Applications that use {@link android.widget.TextView} views automatically benefit from spell
    checking, because {@link android.widget.TextView} automatically uses a spelling checker. The
    following screenshots show this:
</p>
<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_1.png" alt=""
    height="45" id="figure2a" />
<br>
<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_2.png" alt=""
    height="121" id="figure2b" />
<p class="img-caption">
  <strong>Figure 2.</strong> Spell checking in TextView.
</p>
<p>
    However, you may want to interact directly with a spelling checker service in other cases as well.
    The following diagram shows the flow of control for interacting with a spelling checker service:
</p>
<img src="{@docRoot}resources/articles/images/spellcheck_client_flow.png" alt=""
    height="393" id="figure3" />
<p class="img-caption">
  <strong>Figure 3.</strong> Interacting with a spelling checker service.
</p>
<p>
    The <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html">
    Spell Checker Client</a> sample app shows how to interact with a spelling checker service. The
    LatinIME input method editor in the Android Open Source Project also contains an example of
    spell checking.
</p>