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