/ClockBack/CODE-WALK.html
HTML | 315 lines | 311 code | 4 blank | 0 comment | 0 complexity | c15c465de80c4820666c5e9663a56e14 MD5 | raw file
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<body> 4<table cellspacing="0"> 5 <tbody> 6 <tr> 7 <td> 8 <div dir="ltr"> 9 <span dir="ltr">Utilizing Android Accessibility APIs to Provide 10 Alternative and Complementary UI Feedback</span></h3> 11 <h2><b>Objective/Description:</b></h2> 12 This code lab demonstrates how to use the <a 13 href="http://developer.android.com/reference/android/view/accessibility/package-summary.html" 14 target="_blank">Android accessibility APIs</a> to write an <a 15 href="http://developer.android.com/reference/android/accessibilityservice/AccessibilityService.html" 16 target="_blank">accessibility service</a> that provides custom feedback 17 for the Clock application which comes with Android devices. At the end of 18 this exercise, you will have built "ClockBack" which handles only <a 19 href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html" 20 target="_blank">accessibility events</a> from a specific package, 21 changes the provided feedback type based on the device state, utilizes 22 application domain knowledge to enhance the spoken feedback, and 23 demonstrates how the accessibility APIs can be utilized to provide both 24 alternative and complementary UI feedback.<br /> 25 <h2><b>Requirements:</b></h2> 26 The requirements for this codelab is a basic understanding of Android. You 27 should have your <a href="http://developer.android.com/sdk/index.html" 28 target="_blank">Android development environment setup</a> and understand 29 the <a href="http://developer.android.com/guide/index.html" 30 target="_blank">basic concepts</a> of Android development. If you are 31 unfamiliar with Android, we highly recommend that you look at the <a 32 href="http://developer.android.com/" target="_blank">Android 33 developer website</a> and familiarize yourself with developing on Android by 34 trying out the <a 35 href="http://developer.android.com/resources/samples/index.html" 36 target="_blank">code samples</a> there.<br /> 37 <h2><b><b>Background:</b></b></h2> 38 The accessibility APIs are light-weight with no performance impact if 39 accessibility is disabled and are available since release 1.6 of the 40 Android platform. On Android devices each application runs in a separate 41 process. Hence, the applications a user is interacting with and the 42 accessibility services which provide feedback based on that user's actions 43 run in separate processes.<br /> 44 <br /> 45 Therefore, to propagate the information of user interactions to interested 46 accessibility services the Android UI layer is instrumented to fire 47 accessibility events if something interesting happens (say clicking a 48 button). These events are dispatched by the system to the accessibility 49 services which are registered as such and managed by the system. Enabling 50 or disabling an accessibility service happens only upon an explicit user 51 action in the settings menu.<br /> 52 <br /> 53 Accessibility services send an<a 54 href="http://raventhorn.is-into-anime.com/webshare/Drivers/Motorola%20Cell/android-sdk-windows/docs/reference/android/accessibilityservice/AccessibilityServiceInfo.html" 55 target="_blank" rel="nofollow"> accessibility service info</a> to the 56 system with information about how they would like to be handled. An 57 accessibility service can provide a specific feedback type and the system 58 invokes only one accessibility service per feedback type, thus avoiding 59 two accessibility services speaking at the same time. Android devices come 60 with three accessibility services: TalkBack - provides spoken feedback; 61 KickBack - provides haptic feedback; SoundBack - provides audible 62 feedback. <br /> 63 <h2><b>Code-Walk</b>:</h2> 64 <h3>I. Introduction</h3> 65 This code-walk guides you through the process of building an accessibility 66 service which utilizes all the features of the Android accessibility APIs. 67 The exercise is organized in small, incremental steps each exploring a new 68 dimension of functionality that allows you to enhance a provided feedback 69 type as well as to enrich the palette of provided feedback types. The 70 code-walk also gives an example of using the platform APIs to obtain 71 deveice state information and use it to dynamically change the provided 72 feedback. Each step leads you to a running version of "ClockBack", 73 therefore you can go through the process of refining the alternatice and 74 complementary feedback.<br /> 75 <br /> 76 <b>Note</b>: Each of the steps in this code-walk provides a URL to a SVN 77 revision at Google Code. While the code is commented in detail, each 78 revision has review comments which provide a higher level perspective. 79 Since there is rarely a best solution in programming we encourage you to 80 not only try writing the code of each step yourself but also to explore 81 ways of achieving the goals in more optimal and original manner.<br /> 82 <h3> II. Create an Eclipse project form SVN:<br /> 83 </h3> 84 <b>Create an Eclipse project from SVN:</b><br /> 85 <ol> 86 <li>Install <a 87 href="http://www.eclipse.org/subversive/downloads.php" target="_blank" 88 rel="nofollow">Subversive</a>.<br /> 89 </li> 90 <li>Create a new Eclipse project form SVN using as a repository URL 91 (no user name and password needed): 92 http://eyes-free.googlecode.com/svn/trunk/documentation/ClockBackTutorial/Step-By-Step</li> 93 <li>Press "Next" and then "Finish" (Click "Date" and then "Head 94 Revision" to make "Finish" enabled - looks like a minor bug).</li> 95 <li>Select "Checkout as a project configured using the New Project 96 Wizard" and select "Finish"<br /> 97 </li> 98 <li>Select "Android"->"Android project" and press "Next"</li> 99 <li>Enter "ClockBack" as the "Project name" and "Application name".</li> 100 <li>Select "Android 1.6" for "Build Target."</li> 101 <li>Enter "com.google.android.marvin.clockback" as "Package name".<br /> 102 </li> 103 <li>Uncheck "Create Activity".</li> 104 <li>Enter "4" as "Min SDK Version" and press "Finish".</li> 105 <li>Right click on the project, select "Team"->"Synchronize with 106 repository" (For some reason Eclipse does not create the project with 107 all the SVN data).<br /> 108 </li> 109 <li>Right click on the project, select "Override and update..." and 110 press "Yes"</li> 111 <li>Go back to the "Java" perspective go to "Project"->"Android" 112 and select "Android 1.6" (While forcing the update Eclipse forgot our 113 configuration).</li> 114 <li>Clean you project and you are ready to go :)<br /> 115 </li> 116 </ol> 117 <b>Read me:</b> <i> Now you have checked out the latest version of the 118 project and for each step in the tutorial just have to get the content of 119 a given revision by right clicking<br /> 120 on the project->Team->Show History->right click on a given 121 revision(look at the revision number of the left) ->Update to->Yes.</i> 122 <h3>III. Step 0 - spoken feedback 123 for the Clock application<br /> 124 </h3> 125 <b>Update to revision:</b> 574 and visit <a 126 href="http://code.google.com/p/eyes-free/source/detail?r=574" 127 target="_blank">the revision URL</a> to see the code delta and read the 128 review comments.<b><br /> 129 <br /> 130 Step description:</b> This step demonstrates how to write a basic 131 accessibility service which provides spoken feedback for a specific 132 application.<br /> 133 <br /> 134 <b>How to try:</b><br /> 135 <ol> 136 <li>Install "ClockBack" on the device.</li> 137 <li>Enable accessibility: 138 Settings->Accessibility->Accessibility.</li> 139 <li>Enable "ClockBack": Settings->Accessibility->ClockBack.</li> 140 <li>Poke around <u>with the track ball</u> and then go to and 141 explore the Clock application.</li> 142 <li>Try to change the time of an alarm and visit the plus and minus 143 buttons and the hour and minute input fields.</li> 144 </ol> 145 <b>What to expect</b>: Spoken feedback is provided only for the Clock 146 application. However, the plus and minus buttons are not spoken and the 147 hour and minute input fields are not announced as such.<br /> 148 <h3> IV. Step 1 149 - enhance the spoken feedback for the Clock application with domain 150 knowledge<br /> 151 </h3> 152 <b>Update to revision:</b> 575 and visit <a 153 href="http://code.google.com/p/eyes-free/source/detail?r=575" 154 target="_blank">the revision URL</a> to see the code delta and read the 155 review comments.<br /> 156 <br /> 157 <b>Step description:</b> This step demonstrates how to enhance the spoken 158 feedback utilizing domain knowledge. As a result we are properly 159 announcing the plus and minus buttons and the hour and minute input fields 160 in the edit alarm dialog.<br /> 161 <br /> 162 <b>How to try:</b><br /> 163 <ol> 164 <li>Install "ClockBack" on the device.</li> 165 <li>Enable accessibility: 166 Settings->Accessibility->Accessibility.</li> 167 <li>Enable "ClockBack": Settings->Accessibility->ClockBack.</li> 168 <li>Try to change the time of an alarm and visit the plus and minus 169 buttons and the hour and minute input fields.</li> 170 </ol> 171 <b>What to expect</b>: The plus and minus buttons and the hour and minute 172 fields are properly spoken.<br /> 173 <h3> V. Step 2 174 - enhance the spoken feedback by announcing context changes - screen 175 on/off<br /> 176 </h3> 177 <b>Update to revision:</b> 576 and visit <a 178 href="http://code.google.com/p/eyes-free/source/detail?r=576" 179 target="_blank">the revision URL</a> to see the code delta and read the 180 review comments.<br /> 181 <br /> 182 <b>Step description:</b> This step demonstrates how to enhance the spoken 183 feedback by announcing context changes, in our case the screen on/off 184 events.<br /> 185 <br /> 186 <b>How to try:</b><br /> 187 <ol> 188 <li>Install "ClockBack" on the device.</li> 189 <li>Press the Power button on the device to turn the screen on and 190 off</li> 191 </ol> 192 <b>Note:</b> The screen on/off announcement is enabled for all 193 applications since the default accessibility service that provides spoken 194 feedback TalkBack (the version we were developing against) was lacking 195 (the latest TalkBack provides such feedback) this feature.<br /> 196 <br /> 197 <b>What to expect</b>: The screen on and off events are announced 198 including the ringer volume.<br /> 199 <h4><a name="TOC-2.-Create-a-simple-UI-to-show-what-"></a></h4> 200 <h3> VI. Step 3 201 - adding audible feedback to announce ringer mode changes<br /> 202 </h3> 203 <b>Update to revision:</b> 577 and visit <a 204 href="http://code.google.com/p/eyes-free/source/detail?r=577" 205 target="_blank">the revision URL</a> to see the code delta and read the 206 review comments.<br /> 207 <br /> 208 <b>Step description:</b> This step demonstrates how to enhance the spoken 209 feedback by announcing changes in the ringer mode (normal/vibrate/silent).<br /> 210 <br /> 211 <b>How to try:</b><br /> 212 <ol> 213 <li>Install "ClockBack" on the device.</li> 214 <li>Use the ringer volume keys to change the ringer mode.<br /> 215 </li> 216 </ol> 217 <b>Note:</b> The audible feedback for ringer mode change is enabled for 218 all applications since the default accessibility support (at the time we 219 were developing) does not provide such.<br /> 220 <br /> 221 <b>What to expect</b>: A ringer mode specific earcon (short sound) is 222 played upon switching to a given ringer mode.<br /> 223 <h3> VII. Step 224 4 - providing spoken feedback for normal ringer mode and auditory feedback 225 for other ringer modes<br /> 226 </h3> 227 <b>Update to revision:</b> 578 and visit <a 228 href="http://code.google.com/p/eyes-free/source/detail?r=578" 229 target="_blank">the revision URL</a> to see the code delta and read the 230 review comments.<br /> 231 232 <br /> 233 <b>Step description:</b> This step demonstrates how to dynamically change 234 the provided feedback type depending on the ringer mode.<br /> 235 <br /> 236 <b>How to try:</b><br /> 237 <ol> 238 <li>Install "ClockBack" on the device.</li> 239 <li>Enable accessibility: 240 Settings->Accessibility->Accessibility.</li> 241 <li>Enable "ClockBack": Settings->Accessibility->ClockBack.</li> 242 <li>Enable "TalkBack": Settings->Accessibility->TalkBack.</li> 243 <li>Enable "TalkKick": Settings->Accessibility->KickBack.</li> 244 <li>Enable "TalkSound": Settings->Accessibility->SoundBack.</li> 245 <li>Make sure you ringer mode is normal (ringer volume not zero).</li> 246 <li>Poke around in the Clock application.</li> 247 <li>Change the ringer volume to either vibrate or silent.</li> 248 <li>Poke around in the Clock application.</li> 249 <li>Poke around outside of the Clock application.</li> 250 </ol> 251 252 <b>Note:</b> Make sure you start accessibility services in the specified 253 order (application specific ones i.e. ClockBack first). Beginning from the 254 next Android release the default accessibility services will be invoked as 255 fall-back in case no application specific ones exist and the oder of 256 starting services will be irrelevant. <br /> 257 <br /> 258 <b>What to expect</b>: When the ringer mode is normal the feedback in the 259 Clock application is spoken enhanced with domain knowledge (try the change 260 alarm time dialog) and for other ringer modes the feedback is auditory 261 (complementing the visual). However, going outside the application we 262 receive the system wide default feedback.<br /> 263 <h3> VIII. Step 264 5 - providing spoken feedback for normal ringer mode, auditory feedback 265 for vibrate ringer mode, and haptic feedback for ringer silent mode<br /> 266 </h3> 267 <b>Update to revision:</b> 579 and visit <a 268 href="http://code.google.com/p/eyes-free/source/detail?r=579" 269 target="_blank">the revision URL</a> to see the code delta and read the 270 review comments.<br /> 271 <br /> 272 273 <b>Step description:</b> This step demonstrates how to dynamically change 274 the ringer mode depending on the context and use haptic feedback for the 275 silent ringer mode.<br /> 276 <br /> 277 <b>How to try:</b><br /> 278 <ol> 279 <li>Install "ClockBack" on the device.</li> 280 <li>Enable accessibility: 281 Settings->Accessibility->Accessibility.</li> 282 <li>Enable "ClockBack": Settings->Accessibility->ClockBack.</li> 283 <li>Enable "TalkBack": Settings->Accessibility->TalkBack.</li> 284 <li>Enable "TalkKick": Settings->Accessibility->KickBack.</li> 285 <li>Enable "TalkSound": Settings->Accessibility->SoundBack.</li> 286 <li>Make sure you ringer mode is normal (ringer volume not zero).</li> 287 <li>Poke around in the Clock application.</li> 288 <li>Change the ringer volume to vibrate.</li> 289 <li>Poke around in the Clock application.</li> 290 <li>Change the ringer volume to silent.</li> 291 <li>Poke around in the Clock application.</li> 292 </ol> 293 294 <b>Note:</b> Make sure you start accessibility services in the specified 295 order (application specific i.e. ClockBack first). Beginning from the next 296 Android release the default accessibility services will be invoked as 297 fall-back in case no applciation specific ones exist and the oder of 298 starting services will be irrelevant. <br /> 299 <br /> 300 <b>What to expect</b>: When the ringer mode is normal the feedback in the 301 Clock application is spoken enhanced with domain knowledge (try the change 302 alarm time dialog). If the ringer mode is vibrate the provided feedback is 303 auditory and for ringer mode silent the feedback is haptic.<br /> 304 <h3> IX. Step 6 305 - you write a cool accessibility service and we give you win one of our 306 awesome prizes :)</h3> 307 10-x!<br /> 308 <br /> 309 </div> 310 </td> 311 </tr> 312 </tbody> 313</table> 314</body> 315</html>