PageRenderTime 25ms CodeModel.GetById 16ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/ClockBack/CODE-WALK.html

http://eyes-free.googlecode.com/
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"-&gt;"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"-&gt;"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"-&gt;"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-&gt;Team-&gt;Show History-&gt;right click on a given
121      revision(look at the revision number of the left) -&gt;Update to-&gt;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-&gt;Accessibility-&gt;Accessibility.</li>
139        <li>Enable "ClockBack": Settings-&gt;Accessibility-&gt;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-&gt;Accessibility-&gt;Accessibility.</li>
167        <li>Enable "ClockBack": Settings-&gt;Accessibility-&gt;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-&gt;Accessibility-&gt;Accessibility.</li>
241        <li>Enable "ClockBack": Settings-&gt;Accessibility-&gt;ClockBack.</li>
242        <li>Enable "TalkBack": Settings-&gt;Accessibility-&gt;TalkBack.</li>
243        <li>Enable "TalkKick": Settings-&gt;Accessibility-&gt;KickBack.</li>
244        <li>Enable "TalkSound": Settings-&gt;Accessibility-&gt;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-&gt;Accessibility-&gt;Accessibility.</li>
282        <li>Enable "ClockBack": Settings-&gt;Accessibility-&gt;ClockBack.</li>
283        <li>Enable "TalkBack": Settings-&gt;Accessibility-&gt;TalkBack.</li>
284        <li>Enable "TalkKick": Settings-&gt;Accessibility-&gt;KickBack.</li>
285        <li>Enable "TalkSound": Settings-&gt;Accessibility-&gt;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>