| 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> |
| <manifest xmlns:android="http://schemas.android.com/apk/res/android" |
| package="com.example.android.samplespellcheckerservice" > |
| <application |
| android:label="@string/app_name" > |
| <service |
| android:label="@string/app_name" |
| android:name=".SampleSpellCheckerService" |
| android:permission="android.permission.BIND_TEXT_SERVICE" > |
| <intent-filter > |
| <action android:name="android.service.textservice.SpellCheckerService" /> |
| </intent-filter> |
| |
| <meta-data |
| android:name="android.view.textservice.scs" |
| android:resource="@xml/spellchecker" /> |
| </service> |
| |
| <activity |
| android:label="@string/sample_settings" |
| android:name="SpellCheckerSettingsActivity" > |
| <intent-filter > |
| <action android:name="android.intent.action.MAIN" /> |
| </intent-filter> |
| </activity> |
| </application> |
| </manifest> |
| </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> |
| <spell-checker xmlns:android="http://schemas.android.com/apk/res/android" |
| android:label="@string/spellchecker_name" |
| android:settingsActivity="com.example.SpellCheckerSettingsActivity"> |
| <subtype |
| android:label="@string/subtype_generic" |
| android:subtypeLocale="en” |
| /> |
| <subtype |
| android:label="@string/subtype_generic" |
| android:subtypeLocale="fr” |
| /> |
| </spell-checker> |
| </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> |