1 page.title=Spelling Checker Framework 2 page.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 <manifest xmlns:android="http://schemas.android.com/apk/res/android" 153 package="com.example.android.samplespellcheckerservice" > 154 <application 155 android:label="@string/app_name" > 156 <service 157 android:label="@string/app_name" 158 android:name=".SampleSpellCheckerService" 159 android:permission="android.permission.BIND_TEXT_SERVICE" > 160 <intent-filter > 161 <action android:name="android.service.textservice.SpellCheckerService" /> 162 </intent-filter> 163 164 <meta-data 165 android:name="android.view.textservice.scs" 166 android:resource="@xml/spellchecker" /> 167 </service> 168 169 <activity 170 android:label="@string/sample_settings" 171 android:name="SpellCheckerSettingsActivity" > 172 <intent-filter > 173 <action android:name="android.intent.action.MAIN" /> 174 </intent-filter> 175 </activity> 176 </application> 177 </manifest> 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 <spell-checker xmlns:android="http://schemas.android.com/apk/res/android" 190 android:label="@string/spellchecker_name" 191 android:settingsActivity="com.example.SpellCheckerSettingsActivity"> 192 <subtype 193 android:label="@string/subtype_generic" 194 android:subtypeLocale="en 195 /> 196 <subtype 197 android:label="@string/subtype_generic" 198 android:subtypeLocale="fr 199 /> 200 </spell-checker> 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
