Most visited

Recently visited

Added in API level 4

AccessibilityService

public abstract class AccessibilityService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.accessibilityservice.AccessibilityService


Accessibility services are intended to assist users with disabilities in using Android devices and apps. They run in the background and receive callbacks by the system when AccessibilityEvents are fired. Such events denote some state transition in the user interface, for example, the focus has changed, a button has been clicked, etc. Such a service can optionally request the capability for querying the content of the active window. Development of an accessibility service requires extending this class and implementing its abstract methods.

Developer Guides

For more information about creating AccessibilityServices, read the Accessibility developer guide.

Lifecycle

The lifecycle of an accessibility service is managed exclusively by the system and follows the established service life cycle. Starting an accessibility service is triggered exclusively by the user explicitly turning the service on in device settings. After the system binds to a service, it calls onServiceConnected(). This method can be overriden by clients that want to perform post binding setup.

An accessibility service stops either when the user turns it off in device settings or when it calls disableSelf().

Declaration

An accessibility is declared as any other service in an AndroidManifest.xml, but it must do two things:

If either of these items is missing, the system will ignore the accessibility service. Following is an example declaration:

 <service android:name=".MyAccessibilityService"
         android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
     <intent-filter>
         <action android:name="android.accessibilityservice.AccessibilityService" />
     </intent-filter>
     . . .
 </service>

Configuration

An accessibility service can be configured to receive specific types of accessibility events, listen only to specific packages, get events from each type only once in a given time frame, retrieve window content, specify a settings activity, etc.

There are two approaches for configuring an accessibility service:

Retrieving window content

A service can specify in its declaration that it can retrieve window content which is represented as a tree of AccessibilityWindowInfo and AccessibilityNodeInfo objects. Note that declaring this capability requires that the service declares its configuration via an XML resource referenced by SERVICE_META_DATA.

Window content may be retrieved with AccessibilityEvent.getSource(), findFocus(int), getWindows(), or getRootInActiveWindow().

Note An accessibility service may have requested to be notified for a subset of the event types, and thus be unaware when the node hierarchy has changed. It is also possible for a node to contain outdated information because the window content may change at any time.

Notification strategy

All accessibility services are notified of all events they have requested, regardless of their feedback type.

Note: The event notification timeout is useful to avoid propagating events to the client too frequently since this is accomplished via an expensive interprocess call. One can think of the timeout as a criteria to determine when event generation has settled down.

Event types

Feedback types

See also:

Summary

Nested classes

class AccessibilityService.GestureResultCallback

Class used to report status of dispatched gestures  

class AccessibilityService.MagnificationController

Used to control and query the state of display magnification. 

class AccessibilityService.SoftKeyboardController

Used to control and query the soft keyboard show mode. 

Constants

int GESTURE_SWIPE_DOWN

The user has performed a swipe down gesture on the touch screen.

int GESTURE_SWIPE_DOWN_AND_LEFT

The user has performed an down and left gesture on the touch screen.

int GESTURE_SWIPE_DOWN_AND_RIGHT

The user has performed an down and right gesture on the touch screen.

int GESTURE_SWIPE_DOWN_AND_UP

The user has performed a swipe down and up gesture on the touch screen.

int GESTURE_SWIPE_LEFT

The user has performed a swipe left gesture on the touch screen.

int GESTURE_SWIPE_LEFT_AND_DOWN

The user has performed a left and down gesture on the touch screen.

int GESTURE_SWIPE_LEFT_AND_RIGHT

The user has performed a swipe left and right gesture on the touch screen.

int GESTURE_SWIPE_LEFT_AND_UP

The user has performed a left and up gesture on the touch screen.

int GESTURE_SWIPE_RIGHT

The user has performed a swipe right gesture on the touch screen.

int GESTURE_SWIPE_RIGHT_AND_DOWN

The user has performed a right and down gesture on the touch screen.

int GESTURE_SWIPE_RIGHT_AND_LEFT

The user has performed a swipe right and left gesture on the touch screen.

int GESTURE_SWIPE_RIGHT_AND_UP

The user has performed a right and up gesture on the touch screen.

int GESTURE_SWIPE_UP

The user has performed a swipe up gesture on the touch screen.

int GESTURE_SWIPE_UP_AND_DOWN

The user has performed a swipe up and down gesture on the touch screen.

int GESTURE_SWIPE_UP_AND_LEFT

The user has performed an up and left gesture on the touch screen.

int GESTURE_SWIPE_UP_AND_RIGHT

The user has performed an up and right gesture on the touch screen.

int GLOBAL_ACTION_BACK

Action to go back.

int GLOBAL_ACTION_HOME

Action to go home.

int GLOBAL_ACTION_NOTIFICATIONS

Action to open the notifications.

int GLOBAL_ACTION_POWER_DIALOG

Action to open the power long-press dialog.

int GLOBAL_ACTION_QUICK_SETTINGS

Action to open the quick settings.

int GLOBAL_ACTION_RECENTS

Action to toggle showing the overview of recent apps

int GLOBAL_ACTION_TOGGLE_SPLIT_SCREEN

Action to toggle docking the current app's window

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

String SERVICE_META_DATA

Name under which an AccessibilityService component publishes information about itself.

int SHOW_MODE_AUTO

int SHOW_MODE_HIDDEN

Inherited constants

From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2

Public constructors

AccessibilityService()

Public methods

final void disableSelf()

Disables the service.

final boolean dispatchGesture(GestureDescription gesture, AccessibilityService.GestureResultCallback callback, Handler handler)

Dispatch a gesture to the touch screen.

AccessibilityNodeInfo findFocus(int focus)

Find the view that has the specified focus type.

final AccessibilityService.MagnificationController getMagnificationController()

Returns the magnification controller, which may be used to query and modify the state of display magnification.

AccessibilityNodeInfo getRootInActiveWindow()

Gets the root node in the currently active window if this service can retrieve window content.

final AccessibilityServiceInfo getServiceInfo()

Gets the an AccessibilityServiceInfo describing this AccessibilityService.

final AccessibilityService.SoftKeyboardController getSoftKeyboardController()

Returns the soft keyboard controller, which may be used to query and modify the soft keyboard show mode.

Object getSystemService(String name)

Return the handle to a system-level service by name.

List<AccessibilityWindowInfo> getWindows()

Gets the windows on the screen.

abstract void onAccessibilityEvent(AccessibilityEvent event)

Callback for AccessibilityEvents.

final IBinder onBind(Intent intent)

Implement to return the implementation of the internal accessibility service interface.

abstract void onInterrupt()

Callback for interrupting the accessibility feedback.

final boolean performGlobalAction(int action)

Performs a global action.

final void setServiceInfo(AccessibilityServiceInfo info)

Sets the AccessibilityServiceInfo that describes this service.

Protected methods

boolean onGesture(int gestureId)

Called by the system when the user performs a specific gesture on the touch screen.

boolean onKeyEvent(KeyEvent event)

Callback that allows an accessibility service to observe the key events before they are passed to the rest of the system.

void onServiceConnected()

This method is a part of the AccessibilityService lifecycle and is called after the system has successfully bound to the service.

Inherited methods

From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

Constants

GESTURE_SWIPE_DOWN

Added in API level 16
int GESTURE_SWIPE_DOWN

The user has performed a swipe down gesture on the touch screen.

Constant Value: 2 (0x00000002)

GESTURE_SWIPE_DOWN_AND_LEFT

Added in API level 16
int GESTURE_SWIPE_DOWN_AND_LEFT

The user has performed an down and left gesture on the touch screen.

Constant Value: 15 (0x0000000f)

GESTURE_SWIPE_DOWN_AND_RIGHT

Added in API level 16
int GESTURE_SWIPE_DOWN_AND_RIGHT

The user has performed an down and right gesture on the touch screen.

Constant Value: 16 (0x00000010)

GESTURE_SWIPE_DOWN_AND_UP

Added in API level 16
int GESTURE_SWIPE_DOWN_AND_UP

The user has performed a swipe down and up gesture on the touch screen.

Constant Value: 8 (0x00000008)

GESTURE_SWIPE_LEFT

Added in API level 16
int GESTURE_SWIPE_LEFT

The user has performed a swipe left gesture on the touch screen.

Constant Value: 3 (0x00000003)

GESTURE_SWIPE_LEFT_AND_DOWN

Added in API level 16
int GESTURE_SWIPE_LEFT_AND_DOWN

The user has performed a left and down gesture on the touch screen.

Constant Value: 10 (0x0000000a)

GESTURE_SWIPE_LEFT_AND_RIGHT

Added in API level 16
int GESTURE_SWIPE_LEFT_AND_RIGHT

The user has performed a swipe left and right gesture on the touch screen.

Constant Value: 5 (0x00000005)

GESTURE_SWIPE_LEFT_AND_UP

Added in API level 16
int GESTURE_SWIPE_LEFT_AND_UP

The user has performed a left and up gesture on the touch screen.

Constant Value: 9 (0x00000009)

GESTURE_SWIPE_RIGHT

Added in API level 16
int GESTURE_SWIPE_RIGHT

The user has performed a swipe right gesture on the touch screen.

Constant Value: 4 (0x00000004)

GESTURE_SWIPE_RIGHT_AND_DOWN

Added in API level 16
int GESTURE_SWIPE_RIGHT_AND_DOWN

The user has performed a right and down gesture on the touch screen.

Constant Value: 12 (0x0000000c)

GESTURE_SWIPE_RIGHT_AND_LEFT

Added in API level 16
int GESTURE_SWIPE_RIGHT_AND_LEFT

The user has performed a swipe right and left gesture on the touch screen.

Constant Value: 6 (0x00000006)

GESTURE_SWIPE_RIGHT_AND_UP

Added in API level 16
int GESTURE_SWIPE_RIGHT_AND_UP

The user has performed a right and up gesture on the touch screen.

Constant Value: 11 (0x0000000b)

GESTURE_SWIPE_UP

Added in API level 16
int GESTURE_SWIPE_UP

The user has performed a swipe up gesture on the touch screen.

Constant Value: 1 (0x00000001)

GESTURE_SWIPE_UP_AND_DOWN

Added in API level 16
int GESTURE_SWIPE_UP_AND_DOWN

The user has performed a swipe up and down gesture on the touch screen.

Constant Value: 7 (0x00000007)

GESTURE_SWIPE_UP_AND_LEFT

Added in API level 16
int GESTURE_SWIPE_UP_AND_LEFT

The user has performed an up and left gesture on the touch screen.

Constant Value: 13 (0x0000000d)

GESTURE_SWIPE_UP_AND_RIGHT

Added in API level 16
int GESTURE_SWIPE_UP_AND_RIGHT

The user has performed an up and right gesture on the touch screen.

Constant Value: 14 (0x0000000e)

GLOBAL_ACTION_BACK

Added in API level 16
int GLOBAL_ACTION_BACK

Action to go back.

Constant Value: 1 (0x00000001)

GLOBAL_ACTION_HOME

Added in API level 16
int GLOBAL_ACTION_HOME

Action to go home.

Constant Value: 2 (0x00000002)

GLOBAL_ACTION_NOTIFICATIONS

Added in API level 16
int GLOBAL_ACTION_NOTIFICATIONS

Action to open the notifications.

Constant Value: 4 (0x00000004)

GLOBAL_ACTION_POWER_DIALOG

Added in API level 21
int GLOBAL_ACTION_POWER_DIALOG

Action to open the power long-press dialog.

Constant Value: 6 (0x00000006)

GLOBAL_ACTION_QUICK_SETTINGS

Added in API level 17
int GLOBAL_ACTION_QUICK_SETTINGS

Action to open the quick settings.

Constant Value: 5 (0x00000005)

GLOBAL_ACTION_RECENTS

Added in API level 16
int GLOBAL_ACTION_RECENTS

Action to toggle showing the overview of recent apps

Constant Value: 3 (0x00000003)

GLOBAL_ACTION_TOGGLE_SPLIT_SCREEN

Added in API level 24
int GLOBAL_ACTION_TOGGLE_SPLIT_SCREEN

Action to toggle docking the current app's window

Constant Value: 7 (0x00000007)

SERVICE_INTERFACE

Added in API level 4
String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Constant Value: "android.accessibilityservice.AccessibilityService"

SERVICE_META_DATA

Added in API level 14
String SERVICE_META_DATA

Name under which an AccessibilityService component publishes information about itself. This meta-data must reference an XML resource containing an <accessibility-service> tag. This is a a sample XML file configuring an accessibility service:

 <accessibility-service
     android:accessibilityEventTypes="typeViewClicked|typeViewFocused"
     android:packageNames="foo.bar, foo.baz"
     android:accessibilityFeedbackType="feedbackSpoken"
     android:notificationTimeout="100"
     android:accessibilityFlags="flagDefault"
     android:settingsActivity="foo.bar.TestBackActivity"
     android:canRetrieveWindowContent="true"
     android:canRequestTouchExplorationMode="true"
     . . .
 />

Constant Value: "android.accessibilityservice"

SHOW_MODE_AUTO

Added in API level 24
int SHOW_MODE_AUTO

Constant Value: 0 (0x00000000)

SHOW_MODE_HIDDEN

Added in API level 24
int SHOW_MODE_HIDDEN

Constant Value: 1 (0x00000001)

Public constructors

AccessibilityService

Added in API level 4
AccessibilityService ()

Public methods

disableSelf

Added in API level 24
void disableSelf ()

Disables the service. After calling this method, the service will be disabled and settings will show that it is turned off.

dispatchGesture

Added in API level 24
boolean dispatchGesture (GestureDescription gesture, 
                AccessibilityService.GestureResultCallback callback, 
                Handler handler)

Dispatch a gesture to the touch screen. Any gestures currently in progress, whether from the user, this service, or another service, will be cancelled.

The gesture will be dispatched as if it were performed directly on the screen by a user, so the events may be affected by features such as magnification and explore by touch.

Note: In order to dispatch gestures, your service must declare the capability by setting the AccessibilityService_canPerformGestures property in its meta-data. For more information, see SERVICE_META_DATA.

Parameters
gesture GestureDescription: The gesture to dispatch
callback AccessibilityService.GestureResultCallback: The object to call back when the status of the gesture is known. If null, no status is reported.
handler Handler: The handler on which to call back the callback object. If null, the object is called back on the service's main thread.
Returns
boolean true if the gesture is dispatched, false if not.

findFocus

Added in API level 21
AccessibilityNodeInfo findFocus (int focus)

Find the view that has the specified focus type. The search is performed across all windows.

Note: In order to access the windows your service has to declare the capability to retrieve window content by setting the AccessibilityService_canRetrieveWindowContent property in its meta-data. For details refer to SERVICE_META_DATA. Also the service has to opt-in to retrieve the interactive windows by setting the FLAG_RETRIEVE_INTERACTIVE_WINDOWS flag. Otherwise, the search will be performed only in the active window.

Parameters
focus int: The focus to find. One of FOCUS_INPUT or FOCUS_ACCESSIBILITY.
Returns
AccessibilityNodeInfo The node info of the focused view or null.

See also:

getMagnificationController

Added in API level 24
AccessibilityService.MagnificationController getMagnificationController ()

Returns the magnification controller, which may be used to query and modify the state of display magnification.

Note: In order to control magnification, your service must declare the capability by setting the AccessibilityService_canControlMagnification property in its meta-data. For more information, see SERVICE_META_DATA.

Returns
AccessibilityService.MagnificationController the magnification controller

getRootInActiveWindow

Added in API level 16
AccessibilityNodeInfo getRootInActiveWindow ()

Gets the root node in the currently active window if this service can retrieve window content. The active window is the one that the user is currently touching or the window with input focus, if the user is not touching any window.

The currently active window is defined as the window that most recently fired one of the following events: TYPE_WINDOW_STATE_CHANGED, TYPE_VIEW_HOVER_ENTER, TYPE_VIEW_HOVER_EXIT. In other words, the last window shown that also has input focus.

Note: In order to access the root node your service has to declare the capability to retrieve window content by setting the AccessibilityService_canRetrieveWindowContent property in its meta-data. For details refer to SERVICE_META_DATA.

Returns
AccessibilityNodeInfo The root node if this service can retrieve window content.

getServiceInfo

Added in API level 16
AccessibilityServiceInfo getServiceInfo ()

Gets the an AccessibilityServiceInfo describing this AccessibilityService. This method is useful if one wants to change some of the dynamically configurable properties at runtime.

Returns
AccessibilityServiceInfo The accessibility service info.

See also:

getSoftKeyboardController

Added in API level 24
AccessibilityService.SoftKeyboardController getSoftKeyboardController ()

Returns the soft keyboard controller, which may be used to query and modify the soft keyboard show mode.

Returns
AccessibilityService.SoftKeyboardController the soft keyboard controller

getSystemService

Added in API level 4
Object getSystemService (String name)

Return the handle to a system-level service by name. The class of the returned object varies by the requested name. Currently available names are:

WINDOW_SERVICE ("window")
The top-level window manager in which you can place custom windows. The returned object is a WindowManager.
LAYOUT_INFLATER_SERVICE ("layout_inflater")
A LayoutInflater for inflating layout resources in this context.
ACTIVITY_SERVICE ("activity")
A ActivityManager for interacting with the global activity state of the system.
POWER_SERVICE ("power")
A PowerManager for controlling power management.
ALARM_SERVICE ("alarm")
A AlarmManager for receiving intents at the time of your choosing.
NOTIFICATION_SERVICE ("notification")
A NotificationManager for informing the user of background events.
KEYGUARD_SERVICE ("keyguard")
A KeyguardManager for controlling keyguard.
LOCATION_SERVICE ("location")
A LocationManager for controlling location (e.g., GPS) updates.
SEARCH_SERVICE ("search")
A SearchManager for handling search.
VIBRATOR_SERVICE ("vibrator")
A Vibrator for interacting with the vibrator hardware.
CONNECTIVITY_SERVICE ("connection")
A ConnectivityManager for handling management of network connections.
WIFI_SERVICE ("wifi")
A WifiManager for management of Wi-Fi connectivity.
WIFI_P2P_SERVICE ("wifip2p")
A WifiP2pManager for management of Wi-Fi Direct connectivity.
INPUT_METHOD_SERVICE ("input_method")
An InputMethodManager for management of input methods.
UI_MODE_SERVICE ("uimode")
An UiModeManager for controlling UI modes.
DOWNLOAD_SERVICE ("download")
A DownloadManager for requesting HTTP downloads
BATTERY_SERVICE ("batterymanager")
A BatteryManager for managing battery state
JOB_SCHEDULER_SERVICE ("taskmanager")
A JobScheduler for managing scheduled tasks
NETWORK_STATS_SERVICE ("netstats")
A NetworkStatsManager for querying network usage statistics.
HARDWARE_PROPERTIES_SERVICE ("hardware_properties")
A HardwarePropertiesManager for accessing hardware properties.

Note: System services obtained via this API may be closely associated with the Context in which they are obtained from. In general, do not share the service objects between various different contexts (Activities, Applications, Services, Providers, etc.)

Parameters
name String: The name of the desired service.
Returns
Object The service or null if the name does not exist.

getWindows

Added in API level 21
List<AccessibilityWindowInfo> getWindows ()

Gets the windows on the screen. This method returns only the windows that a sighted user can interact with, as opposed to all windows. For example, if there is a modal dialog shown and the user cannot touch anything behind it, then only the modal window will be reported (assuming it is the top one). For convenience the returned windows are ordered in a descending layer order, which is the windows that are higher in the Z-order are reported first. Since the user can always interact with the window that has input focus by typing, the focused window is always returned (even if covered by a modal window).

Note: In order to access the windows your service has to declare the capability to retrieve window content by setting the AccessibilityService_canRetrieveWindowContent property in its meta-data. For details refer to SERVICE_META_DATA. Also the service has to opt-in to retrieve the interactive windows by setting the FLAG_RETRIEVE_INTERACTIVE_WINDOWS flag.

Returns
List<AccessibilityWindowInfo> The windows if there are windows and the service is can retrieve them, otherwise an empty list.

onAccessibilityEvent

Added in API level 4
void onAccessibilityEvent (AccessibilityEvent event)

Callback for AccessibilityEvents.

Parameters
event AccessibilityEvent: The new event. This event is owned by the caller and cannot be used after this method returns. Services wishing to use the event after this method returns should make a copy.

onBind

Added in API level 4
IBinder onBind (Intent intent)

Implement to return the implementation of the internal accessibility service interface.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Returns
IBinder Return an IBinder through which clients can call on to the service.

onInterrupt

Added in API level 4
void onInterrupt ()

Callback for interrupting the accessibility feedback.

performGlobalAction

Added in API level 16
boolean performGlobalAction (int action)

Performs a global action. Such an action can be performed at any moment regardless of the current application or user location in that application. For example going back, going home, opening recents, etc.

Parameters
action int: The action to perform.
Returns
boolean Whether the action was successfully performed.

See also:

setServiceInfo

Added in API level 4
void setServiceInfo (AccessibilityServiceInfo info)

Sets the AccessibilityServiceInfo that describes this service.

Note: You can call this method any time but the info will be picked up after the system has bound to this service and when this method is called thereafter.

Parameters
info AccessibilityServiceInfo: The info.

Protected methods

onGesture

Added in API level 16
boolean onGesture (int gestureId)

Called by the system when the user performs a specific gesture on the touch screen. Note: To receive gestures an accessibility service must request that the device is in touch exploration mode by setting the FLAG_REQUEST_TOUCH_EXPLORATION_MODE flag.

Parameters
gestureId int: The unique id of the performed gesture.
Returns
boolean Whether the gesture was handled.

See also:

onKeyEvent

Added in API level 18
boolean onKeyEvent (KeyEvent event)

Callback that allows an accessibility service to observe the key events before they are passed to the rest of the system. This means that the events are first delivered here before they are passed to the device policy, the input method, or applications.

Note: It is important that key events are handled in such a way that the event stream that would be passed to the rest of the system is well-formed. For example, handling the down event but not the up event and vice versa would generate an inconsistent event stream.

Note: The key events delivered in this method are copies and modifying them will have no effect on the events that will be passed to the system. This method is intended to perform purely filtering functionality.

Parameters
event KeyEvent: The event to be processed. This event is owned by the caller and cannot be used after this method returns. Services wishing to use the event after this method returns should make a copy.
Returns
boolean If true then the event will be consumed and not delivered to applications, otherwise it will be delivered as usual.

onServiceConnected

Added in API level 4
void onServiceConnected ()

This method is a part of the AccessibilityService lifecycle and is called after the system has successfully bound to the service. If is convenient to use this method for setting the AccessibilityServiceInfo.

See also:

Hooray!