1page.title=Building Accessibility Services 2parent.title=Accessibility 3parent.link=index.html 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9 <h2>Topics</h2> 10 <ol> 11 <li><a href="#manifest">Manifest Declarations and Permissions</a> 12 <ol> 13 <li><a href="service-declaration">Accessibility service declaration</a></li> 14 <li><a href="#service-config">Accessibility service configuration</a></li> 15 </ol> 16 </li> 17 <li><a href="#methods">AccessibilityService Methods</a></li> 18 <li><a href="#event-details">Getting Event Details</a></li> 19 <li><a href="#examples">Example Code</a></li> 20 </ol> 21 22 <h2>Key classes</h2> 23 <ol> 24 <li>{@link android.accessibilityservice.AccessibilityService}</li> 25 <li>{@link android.accessibilityservice.AccessibilityServiceInfo}</li> 26 <li>{@link android.view.accessibility.AccessibilityEvent}</li> 27 <li>{@link android.view.accessibility.AccessibilityRecord}</li> 28 <li>{@link android.view.accessibility.AccessibilityNodeInfo}</li> 29 </ol> 30 31 <h2>See also</h2> 32 <ol> 33 <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> 34 </ol> 35 36</div> 37</div> 38 39<p>An accessibility service is an application that provides user interface enhancements to 40assist users with disabilities, or who may temporarily be unable to fully interact with a device. 41For example, users who are driving, taking care of a young child or attending a very loud party 42might need additional or alternative interface feedback.</p> 43 44<p>Android provides standard accessibility services, including TalkBack, and developers can 45create and distribute their own services. This document explains the basics of building an 46accessibility service.</p> 47 48<p>The ability for you to build and deploy accessibility services was introduced with Android 491.6 (API Level 4) and received significant improvements with Android 4.0 (API Level 14). The Android 50Support Library was also updated with the release of Android 4.0 to provide support for these 51enhanced accessibility features back to Android 1.6. Developers aiming for widely compatible 52accessibility services are encouraged to use the 53<a href="{@docRoot}tools/extras/support-library.html">Support Library</a> and develop for the more 54advanced accessibility features introduced in Android 4.0.</p> 55 56 57<h2 id="manifest">Manifest Declarations and Permissions</h2> 58 59<p>Applications that provide accessibility services must include specific declarations in their 60 application manifests in order to be treated as an accessibility service by an Android system. 61 This section explains the required and optional settings for accessibility services.</p> 62 63 64<h3 id="service-declaration">Accessibility service declaration</h3> 65 66<p>In order to be treated as an accessibility service, your application must include the 67{@code service} element (rather than the {@code activity} element) within the {@code application} 68element in its manifest. In addition, within the {@code service} element, you must also include an 69accessibility service intent filter, as shown in the following sample:</p> 70 71<pre> 72<application> 73 <service android:name=".MyAccessibilityService" 74 android:label="@string/accessibility_service_label"> 75 <intent-filter> 76 <action android:name="android.accessibilityservice.AccessibilityService" /> 77 </intent-filter> 78 </service> 79</application> 80</pre> 81 82<p>These declarations are required for all accessibility services deployed on Android 1.6 (API Level 83 4) or higher.</p> 84 85 86<h3 id="service-config">Accessibility service configuration</h3> 87 88<p>Accessibility services must also provide a configuration which specifies the types of 89accessibility events that the service handles and additional information about the service. The 90configuration of an accessibility service is contained in the {@link 91android.accessibilityservice.AccessibilityServiceInfo} class. Your service can build and set a 92configuration using an instance of this class and {@link 93android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()} at runtime. 94However, not all configuration options are available using this method.</p> 95 96<p>Beginning with Android 4.0, you can include a {@code <meta-data>} element in your manifest 97with a reference to a configuration file, which allows you to set the full range of options for 98your accessibility service, as shown in the following example:</p> 99 100<pre> 101<service android:name=".MyAccessibilityService"> 102 ... 103 <meta-data 104 android:name="android.accessibilityservice" 105 android:resource="@xml/accessibility_service_config" /> 106</service> 107</pre> 108 109<p>This meta-data element refers to an XML file that you create in your application’s resource 110directory ({@code <project_dir>/res/xml/accessibility_service_config.xml}). The following code 111shows example contents for the service configuration file:</p> 112 113<pre> 114<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android" 115 android:description="@string/accessibility_service_description" 116 android:packageNames="com.example.android.apis" 117 android:accessibilityEventTypes="typeAllMask" 118 android:accessibilityFlags="flagDefault" 119 android:accessibilityFeedbackType="feedbackSpoken" 120 android:notificationTimeout="100" 121 android:canRetrieveWindowContent="true" 122 android:settingsActivity="com.example.android.accessibility.ServiceSettingsActivity" 123/> 124</pre> 125 126<p>One of the most important functions of the accessibility service configuration parameters is to 127allow you to specify what types of accessibility events your service can handle. Being able to 128specify this information enables accessibility services to cooperate with each other, and allows you 129as a developer the flexibility to handle only specific events types from specific applications. The 130event filtering can include the following criteria:</p> 131 132<ul> 133 <li><strong>Package Names</strong> - Specify the package names of applications whose accessibility 134events you want your service to handle. If this parameter is omitted, your accessibility service is 135considered available to service accessibility events for any application. This parameter can be set 136in the accessibility service configuration files with the {@code android:packageNames} attribute as 137a comma-separated list, or set using the {@link 138android.accessibilityservice.AccessibilityServiceInfo#packageNames 139AccessibilityServiceInfo.packageNames} member.</li> 140 <li><strong>Event Types</strong> - Specify the types of accessibility events you want your service 141to handle. This parameter can be set in the accessibility service configuration files with the 142{@code android:accessibilityEventTypes} attribute as a comma-separated list, or set using the 143{@link android.accessibilityservice.AccessibilityServiceInfo#eventTypes 144AccessibilityServiceInfo.eventTypes} member. </li> 145</ul> 146 147<p>For more information about the XML attributes which can be used in the accessibility service 148 configuration file, follow these links to the reference documentation:</p> 149 150<ul> 151 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_description">{@code android:description}</a></li> 152 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_packageNames">{@code android:packageNames}</a></li> 153 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityEventTypes">{@code android:accessibilityEventTypes}</a></li> 154 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFlags">{@code android:accessibilityFlags}</a></li> 155 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFeedbackType">{@code android:accessibilityFeedbackType}</a></li> 156 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_notificationTimeout">{@code android:notificationTimeout}</a></li> 157 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_canRetrieveWindowContent">{@code android:canRetrieveWindowContent}</a></li> 158 <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_settingsActivity">{@code android:settingsActivity}</a></li> 159</ul> 160 161<p>For more information about which configuration settings can be dynamically set at runtime, see 162the {@link android.accessibilityservice.AccessibilityServiceInfo} reference documentation.</p> 163 164 165<h2 id="methods">AccessibilityService Methods</h2> 166 167<p>An application that provides accessibility service must extend the {@link 168android.accessibilityservice.AccessibilityService} class and override the following methods from 169that class. These methods are presented in the order in which they are called by the Android system, 170from when the service is started 171({@link android.accessibilityservice.AccessibilityService#onServiceConnected onServiceConnected()}), 172while it is running ({@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent 173onAccessibilityEvent()}, 174{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()}) to when it is 175shut down ({@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()}).</p> 176 177<ul> 178 <li>{@link android.accessibilityservice.AccessibilityService#onServiceConnected 179onServiceConnected()} - (optional) This system calls this method when it successfully connects to 180your accessibility service. Use this method to do any one-time setup steps for your service, 181including connecting to user feedback system services, such as the audio manager or device vibrator. 182If you want to set the configuration of your service at runtime or make one-time adjustments, this 183is a convenient location from which to call {@link 184android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()}.</li> 185 186 <li>{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent 187onAccessibilityEvent()} - (required) This method is called back by the system when it detects an 188{@link android.view.accessibility.AccessibilityEvent} that matches the event filtering parameters 189specified by your accessibility service. For example, when the user clicks a button or focuses on a 190user interface control in an application for which your accessibility service is providing feedback. 191When this happens, the system calls this method of your service with the associated {@link 192android.view.accessibility.AccessibilityEvent}, which you can then interpret and provide feedback to 193the user. This method may be called many times over the lifecycle of your service.</li> 194 195 <li>{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()} - 196(required) This method is called when the system wants to interrupt the feedback your service is 197providing, usually in response to a user taking action, such as moving focus to a different user 198interface control than the one for which you are currently providing feedback. This method may be 199called many times over the lifecycle of your service.</li> 200 201 <li>{@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()} - (optional) 202This method is called when the system is about to shutdown the accessibility service. Use this 203method to do any one-time shutdown procedures, including de-allocating user feedback system 204services, such as the audio manager or device vibrator.</li> 205</ul> 206 207<p>These callback methods provide the basic structure for your accessibility service. It is up to 208you to decide on how to process data provided by the Android system in the form of {@link 209android.view.accessibility.AccessibilityEvent} objects and provide feedback to the user.</p> 210 211 212<h2 id="event-details">Getting Event Details</h2> 213 214<p>The Android system provides information to accessibility services about the user interface 215interaction through {@link android.view.accessibility.AccessibilityEvent} objects. Prior to Android 2164.0, the information available in an accessibility event, while providing a significant amount of 217detail about a user interface control selected by the user, typically provided limited contextual 218information. In many cases, this missing context information might be critical to understanding the 219meaning of the selected control.</p> 220 221<p>A typical example of an interface where context is of critical importance is a calendar or day 222planner. If a user selects a 4:00 PM time slot in a Monday to Friday day list and the accessibility 223service announces “4 PM”, but fails to indicate this is a Friday a Monday, the month or day, this is 224hardly ideal feedback for the user. In this case, the context of a user interface control is of 225critical importance to a user who wants to schedule a meeting.</p> 226 227<p>Android 4.0 significantly extends the amount of information that an accessibility service can 228obtain about an user interface interaction by composing accessibility events based on the view 229hierarchy. A view hierarchy is the set of user interface components that contain the component (its 230parents) and the user interface elements that may be contained by that component (its children). In 231this way, the Android system can provide much richer detail about accessibility events, allowing 232accessibility services to provide more useful feedback to users.</p> 233 234<p>An accessibility service gets information about an user interface event through an {@link 235android.view.accessibility.AccessibilityEvent} passed by the system to the service’s 236{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent 237onAccessibilityEvent()} callback method. This object provides details about the event, including the 238type of object being acted upon, its descriptive text and other details. Starting in Android 4.0 239(and supported in previous releases through the {@link 240android.support.v4.view.accessibility.AccessibilityEventCompat} object in the Support Library), you 241can obtain additional information about the event using these calls:</p> 242 243<ul> 244 <li>{@link android.view.accessibility.AccessibilityEvent#getRecordCount 245AccessibilityEvent.getRecordCount()} and {@link 246android.view.accessibility.AccessibilityEvent#getRecord getRecord(int)} - These methods allow you to 247retrieve the set of {@link android.view.accessibility.AccessibilityRecord} objects which contributed 248to the {@link android.view.accessibility.AccessibilityEvent} passed to you by the system, which can 249provide more context for your accessibility service.</li> 250 251 <li>{@link android.view.accessibility.AccessibilityEvent#getSource 252AccessibilityEvent.getSource()} - This method returns an {@link 253android.view.accessibility.AccessibilityNodeInfo} object. This object allows you to request the 254parents and children of the component that originated the accessibility event and investigate their 255contents and state in order to provide 256 257 <p class="caution"><strong>Important:</strong> The ability to investigate the full view 258hierarchy from an {@link android.view.accessibility.AccessibilityEvent} potentially exposes private 259user information to your accessibility service. For this reason, your service must request this 260level of access through the accessibility <a href="#service-config">service configuration XML</a> 261file, by including the {@code canRetrieveWindowContent} attribute and setting it to {@code true}. If 262you do not include this setting in your service configuration xml file, calls to {@link 263android.view.accessibility.AccessibilityEvent#getSource getSource()} fail.</p> 264 </li> 265</ul> 266 267 268<h2 id="examples">Example Code</h2> 269 270<p>The API Demo project contains two samples which can be used as a starting point for generating 271accessibility services 272({@code <sdk>/samples/<platform>/ApiDemos/src/com/example/android/apis/accessibility}): 273</p> 274 275<ul> 276 <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/ClockBackService.html">ClockBackService</a> 277 - This service is based on the original implementation of {@link 278android.accessibilityservice.AccessibilityService} and can be used as a base for developing basic 279accessibility services that are compatible with Android 1.6 (API Level 4) and higher.</li> 280 <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/TaskBackService.html">TaskBackService</a> 281 - This service is based on the enhanced accessibility APIs introduced in Android 4.0 (API Level 28214). However, you can use the Android <a href="{@docRoot}tools/extras/support-library.html">Support 283Libary</a> to substitute classes introduced in later API levels (e.g., 284{@link android.view.accessibility.AccessibilityRecord}, 285{@link android.view.accessibility.AccessibilityNodeInfo} 286) with equivalent support package classes (e.g., 287{@link android.support.v4.view.accessibility.AccessibilityRecordCompat}, 288{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} 289) to make this example work with API versions back to Android 1.6 (API Level 4).</li> 290</ul> 291