• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.title=Spelling Checker Framework
2page.tags="input","spellcheckerservice"
3@jd:body
4<div id="qv-wrapper">
5<div id="qv">
6<h2>In This Document</h2>
7<ol>
8    <li>
9        <a href="#SpellCheckLifeCycle">Spell Check Lifecycle</a>
10    </li>
11    <li>
12        <a href="#SpellCheckImplementation">Implementing a Spell Checker Service</a>
13    </li>
14    <li>
15        <a href="#SpellCheckClient">Implementing a Spell Checker Client</a>
16    </li>
17</ol>
18  <h2>See also</h2>
19  <ol>
20    <li>
21        <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html">
22        Spell Checker Service</a> sample app
23    </li>
24    <li>
25        <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html">
26        Spell Checker Client</a> sample app
27    </li>
28  </ol>
29</div>
30</div>
31
32<p>
33    The Android platform offers a spelling checker framework that lets you implement
34    and access spell checking in your application. The framework is one of the
35    Text Service APIs offered by the Android platform.
36</p>
37<p>
38    To use the framework in your app, you create a special type of Android service that
39    generates a spelling checker <strong>session</strong> object. Based on text you provide,
40    the session object returns spelling suggestions generated by the spelling checker.
41</p>
42<h2 id="SpellCheckLifeCycle">Spell Checker Lifecycle</h2>
43<p>
44    The following diagram shows the lifecycle of the spelling checker service:
45</p>
46<img src="{@docRoot}resources/articles/images/spellcheck_lifecycle.png" alt="" height="596"
47    id="figure1" />
48<p class="img-caption">
49  <strong>Figure 1.</strong> The spelling checker service lifecycle.
50</p>
51<p>
52    To initiate spell checking, your app starts its implementation of the spelling checker
53    service. Clients in your app, such as activities or individual UI elements, request a
54    spelling checker session from the service, then use the session to get suggestions for text.
55    As a client terminates its operation, it closes its spelling checker session. If necessary, your
56    app can shut down the spelling checker service at any time.
57</p>
58<h2 id="SpellCheckImplementation">Implementing a Spell Checker Service</h2>
59<p>
60    To use the spelling checker framework in your app, add a spelling checker service component including
61    the session object definition. You can also add to your app an optional activity that
62    controls settings. You must also add an XML metadata file that describes
63    the spelling checker service, and add the appropriate elements to your manifest file.
64</p>
65<h3 id="SpellCheckCode">Spell checker classes</h3>
66<p>
67    Define the service and session object with the following classes:
68</p>
69<dl>
70    <dt>
71        A subclass of {@link android.service.textservice.SpellCheckerService}
72    </dt>
73    <dd>
74        The {@link android.service.textservice.SpellCheckerService} implements both the
75        {@link android.app.Service} class and the spelling checker framework interface. Within your
76        subclass, you must implement the following method:
77        <dl>
78            <dt>{@link android.service.textservice.SpellCheckerService#createSession()}</dt>
79            <dd>
80                A factory method that returns a
81                {@link android.service.textservice.SpellCheckerService.Session} object to a
82                client that wants to do spell checking.
83            </dd>
84        </dl>
85        <p>
86            See the
87            <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html">
88            Spell Checker Service</a> sample app to learn more about implementing this class.
89        </p>
90    </dd>
91    <dt>
92        An implementation of {@link android.service.textservice.SpellCheckerService.Session}
93    </dt>
94    <dd>
95        An object that the spelling checker service provides to clients, to let them pass text to
96        the spelling checker and receive suggestions. Within this class, you must implement the
97        following methods:
98        <dl>
99            <dt>
100                {@link android.service.textservice.SpellCheckerService.Session#onCreate()}
101            </dt>
102            <dd>
103                Called by the system in response to
104                {@link android.service.textservice.SpellCheckerService#createSession()}. In this
105                method, you can initialize the
106                {@link android.service.textservice.SpellCheckerService.Session} object based on
107                the current locale and so forth.
108            </dd>
109            <dt>
110     {@link android.service.textservice.SpellCheckerService.Session#onGetSentenceSuggestionsMultiple(TextInfo[], int)
111     onGetSentenceSuggestionsMultiple()}
112            </dt>
113            <dd>
114                Does the actual spell checking. This method returns an array of
115                {@link android.view.textservice.SentenceSuggestionsInfo} containing
116                suggestions for the sentences passed to it.
117            </dd>
118        </dl>
119        <p>
120            Optionally, you can implement
121            {@link android.service.textservice.SpellCheckerService.Session#onCancel()}, which
122            handles requests to cancel spell checking,
123            {@link android.service.textservice.SpellCheckerService.Session#onGetSuggestions(TextInfo, int)
124            onGetSuggestions()}, which handles a word suggestion request, or
125            {@link android.service.textservice.SpellCheckerService.Session#onGetSuggestionsMultiple(TextInfo[], int, boolean)
126            onGetSuggestionsMultiple()}, which handles batches of word suggestion requests.
127        </p>
128        <p>
129            See the
130            <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html">
131            Spell Checker Client</a> sample app to learn more about implementing this class.
132        </p>
133    </dd>
134</dl>
135<p class="note">
136    <strong>Note:</strong> You must implement all aspects of spell checking as asynchronous and
137    thread-safe. A spelling checker may be called simultaneously by different threads running on
138    different cores. The {@link android.service.textservice.SpellCheckerService} and
139    {@link android.service.textservice.SpellCheckerService.Session} take care of this
140    automatically.
141</p>
142<h3 id="SpellCheckXML">Spell checker manifest and metadata</h3>
143<p>
144    In addition to code, you need to provide the appropriate manifest file and a metadata file for
145    the spelling checker.
146</p>
147<p>
148    The manifest file defines the application, the service, and the activity for controlling
149    settings, as shown in the following snippet:
150</p>
151<pre>
152&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
153    package="com.example.android.samplespellcheckerservice" &gt;
154    &lt;application
155        android:label="&#64;string/app_name" &gt;
156        &lt;service
157            android:label="&#64;string/app_name"
158            android:name=".SampleSpellCheckerService"
159            android:permission="android.permission.BIND_TEXT_SERVICE" &gt;
160            &lt;intent-filter &gt;
161                &lt;action android:name="android.service.textservice.SpellCheckerService" /&gt;
162            &lt;/intent-filter&gt;
163
164            &lt;meta-data
165                android:name="android.view.textservice.scs"
166                android:resource="&#64;xml/spellchecker" /&gt;
167        &lt;/service&gt;
168
169        &lt;activity
170            android:label="&#64;string/sample_settings"
171            android:name="SpellCheckerSettingsActivity" &gt;
172            &lt;intent-filter &gt;
173                &lt;action android:name="android.intent.action.MAIN" /&gt;
174            &lt;/intent-filter&gt;
175        &lt;/activity&gt;
176    &lt;/application&gt;
177&lt;/manifest&gt;
178</pre>
179<p>
180    Notice that components that want to use the service must request the permission
181    {@link android.Manifest.permission#BIND_TEXT_SERVICE} to ensure that only the system binds to
182    the service. The service's definition also specifies the <code>spellchecker.xml</code> metadata
183    file, which is described in the next section.
184</p>
185<p>
186    The metadata file <code>spellchecker.xml</code> contains the following XML:
187</p>
188<pre>
189&lt;spell-checker xmlns:android="http://schemas.android.com/apk/res/android"
190        android:label="&#64;string/spellchecker_name"
191        android:settingsActivity="com.example.SpellCheckerSettingsActivity"&gt;
192    &lt;subtype
193            android:label="&#64;string/subtype_generic"
194            android:subtypeLocale="en”
195    /&gt;
196    &lt;subtype
197            android:label="&#64;string/subtype_generic"
198            android:subtypeLocale="fr”
199    /&gt;
200&lt;/spell-checker&gt;
201</pre>
202<p>
203    The metadata specifies the activity that the spelling checker uses for controlling settings. It
204    also defines subtypes for the spelling checker; in this case, the subtypes define locales that
205    the spelling checker can handle.
206</p>
207
208
209<!--  Accessing the Spell Checker Service from a Client -->
210<h2 id="SpellCheckClient">Accessing the Spell Checker Service from a Client</h2>
211<p>
212    Applications that use {@link android.widget.TextView} views automatically benefit from spell
213    checking, because {@link android.widget.TextView} automatically uses a spelling checker. The
214    following screenshots show this:
215</p>
216<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_1.png" alt=""
217    height="45" id="figure2a" />
218<br>
219<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_2.png" alt=""
220    height="121" id="figure2b" />
221<p class="img-caption">
222  <strong>Figure 2.</strong> Spell checking in TextView.
223</p>
224<p>
225    However, you may want to interact directly with a spelling checker service in other cases as well.
226    The following diagram shows the flow of control for interacting with a spelling checker service:
227</p>
228<img src="{@docRoot}resources/articles/images/spellcheck_client_flow.png" alt=""
229    height="393" id="figure3" />
230<p class="img-caption">
231  <strong>Figure 3.</strong> Interacting with a spelling checker service.
232</p>
233<p>
234    The <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html">
235    Spell Checker Client</a> sample app shows how to interact with a spelling checker service. The
236    LatinIME input method editor in the Android Open Source Project also contains an example of
237    spell checking.
238</p>
239