diff options
Diffstat (limited to 'docs/html/resources/articles/spell-checker-framework.jd')
| -rw-r--r-- | docs/html/resources/articles/spell-checker-framework.jd | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/docs/html/resources/articles/spell-checker-framework.jd b/docs/html/resources/articles/spell-checker-framework.jd new file mode 100644 index 0000000..8d57b4e --- /dev/null +++ b/docs/html/resources/articles/spell-checker-framework.jd @@ -0,0 +1,236 @@ +page.title=Using the Spell Checker Framework +parent.title=Articles +parent.link=../browser.html?tag=article +@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 spell 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 spell checker <strong>session</strong> object. Based on text you provide, + the session object returns spelling suggestions generated by the spell checker. +</p> +<h2 id="SpellCheckLifeCycle">Spell Checker Lifecycle</h2> +<p> + The following diagram shows the lifecycle of the spell 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 spell checker service lifecycle. +</p> +<p> + To initiate spell checking, your app starts its implementation of the spell checker + service. Clients in your app, such as activities or individual UI elements, request a + spell checker session from the service, then use the session to get suggestions for text. + As a client terminates its operation, it closes its spell checker session. If necessary, your + app can shut down the spell checker service at any time. +</p> +<h2 id="SpellCheckImplementation">Implementing a Spell Checker Service</h2> +<p> + To use the spell checker framework in your app, add a spell 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 spell 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 spell 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 spell checker service provides to clients, to let them pass text to + the spell 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#onGetSuggestions(TextInfo, int) + onGetSuggestions()} + </dt> + <dd> + Does the actual spell checking. This method returns an object containing + suggestions for the text passed to it. + </dd> + </dl> + <p> + Optionally, you can implement + {@link android.service.textservice.SpellCheckerService.Session#onCancel()}, which + handles requests to cancel spell checking, or +{@link android.service.textservice.SpellCheckerService.Session#onGetSuggestionsMultiple(TextInfo[], int, boolean) +onGetSuggestionsMultiple()}, which handles batches of suggestion requests, or both. + </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 spell 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 spell 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 spell checker uses for controlling settings. It + also defines subtypes for the spell checker; in this case, the subtypes define locales that + the spell 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 spell 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 spell checker service in other cases as well. + The following diagram shows the flow of control for interacting with a spell checker service: +</p> +<img src="{@docRoot}resources/articles/images/spellcheck_client_flow.png" alt="" + height="394" id="figure3" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Interacting with a spell 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 spell checker service. The + LatinIME input method editor in the Android Open Source Project also contains an example of + spell checking. +</p>
\ No newline at end of file |