Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit fbc72804 authored by Phil Weaver's avatar Phil Weaver Committed by Android (Google) Code Review
Browse files

Merge "Clean up some accessibility documentation."

parents 7b9f2e1d 40ded287

core/java/android/accessibilityservice/AccessibilityService.java

+46 −53
Original line number Diff line number Diff line
@@ -49,7 +49,8 @@ import com.android.internal.os.SomeArgs; 
import java.util.List;



/**

 * An accessibility service runs in the background and receives callbacks by the system

 * 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 {@link AccessibilityEvent}s 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
@@ -66,22 +67,31 @@ import java.util.List; 
 * <h3>Lifecycle</h3>

 * <p>

 * The lifecycle of an accessibility service is managed exclusively by the system and

 * follows the established service life cycle. Additionally, starting or stopping an

 * accessibility service is triggered exclusively by an explicit user action through

 * enabling or disabling it in the device settings. After the system binds to a service it

 * calls {@link AccessibilityService#onServiceConnected()}. This method can be

 * overriden by clients that want to perform post binding setup.

 * 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 {@link AccessibilityService#onServiceConnected()}. This method can

 * be overriden by clients that want to perform post binding setup.

 * </p>

 * <p>

 * An accessibility service stops either when the user turns it off in device settings or when

 * it calls {@link AccessibilityService#disableSelf()}.

 * </p>

 * <h3>Declaration</h3>

 * <p>

 * An accessibility is declared as any other service in an AndroidManifest.xml but it

 * must also specify that it handles the "android.accessibilityservice.AccessibilityService"

 * {@link android.content.Intent}. Failure to declare this intent will cause the system to

 * ignore the accessibility service. Additionally an accessibility service must request the

 * {@link android.Manifest.permission#BIND_ACCESSIBILITY_SERVICE} permission to ensure

 * that only the system

 * can bind to it. Failure to declare this intent will cause the system to ignore the

 * accessibility service. Following is an example declaration:

 * An accessibility is declared as any other service in an AndroidManifest.xml, but it

 * must do two things:

 * <ul>

 *     <ol>

 *         Specify that it handles the "android.accessibilityservice.AccessibilityService"

 *         {@link android.content.Intent}.

 *     </ol>

 *     <ol>

 *         Request the {@link android.Manifest.permission#BIND_ACCESSIBILITY_SERVICE} permission to

 *         ensure that only the system can bind to it.

 *     </ol>

 * </ul>

 * If either of these items is missing, the system will ignore the accessibility service.

 * Following is an example declaration:

 * </p>

 * <pre> &lt;service android:name=".MyAccessibilityService"

 *         android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"&gt;
@@ -135,48 +145,24 @@ import java.util.List; 
 * </ul>

 * <h3>Retrieving window content</h3>

 * <p>

 * A service can specify in its declaration that it can retrieve the active window

 * content which is represented as a tree of {@link AccessibilityNodeInfo}. Note that

 * A service can specify in its declaration that it can retrieve window

 * content which is represented as a tree of {@link AccessibilityWindowInfo} and

 * {@link AccessibilityNodeInfo} objects. Note that

 * declaring this capability requires that the service declares its configuration via

 * an XML resource referenced by {@link #SERVICE_META_DATA}.

 * </p>

 * <p>

 * For security purposes an accessibility service can retrieve only the content of the

 * currently active window. The currently active window is defined as the window from

 * which was fired the last event of the following types:

 * {@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED},

 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER},

 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT},

 * In other words, the last window that was shown or the last window that the user has touched

 * during touch exploration.

 * </p>

 * <p>

 * The entry point for retrieving window content is through calling

 * {@link AccessibilityEvent#getSource() AccessibilityEvent.getSource()} of the last received

 * event of the above types or a previous event from the same window

 * (see {@link AccessibilityEvent#getWindowId() AccessibilityEvent.getWindowId()}). Invoking

 * this method will return an {@link AccessibilityNodeInfo} that can be used to traverse the

 * window content which represented as a tree of such objects.

 * Window content may be retrieved with

 * {@link AccessibilityEvent#getSource() AccessibilityEvent.getSource()},

 * {@link AccessibilityService#findFocus(int)},

 * {@link AccessibilityService#getWindows()}, or

 * {@link AccessibilityService#getRootInActiveWindow()}.

 * </p>

 * <p class="note">

 * <strong>Note</strong> An accessibility service may have requested to be notified for

 * a subset of the event types, thus be unaware that the active window has changed. Therefore

 * accessibility service that would like to retrieve window content should:

 * <ul>

 * <li>

 * Register for all event types with no notification timeout and keep track for the active

 * window by calling {@link AccessibilityEvent#getWindowId()} of the last received event and

 * compare this with the {@link AccessibilityNodeInfo#getWindowId()} before calling retrieval

 * methods on the latter.

 * </li>

 * <li>

 * Prepare that a retrieval method on {@link AccessibilityNodeInfo} may fail since the

 * active window has changed and the service did not get the accessibility event yet. Note

 * that it is possible to have a retrieval method failing even adopting the strategy

 * specified in the previous bullet because the accessibility event dispatch is asynchronous

 * and crosses process boundaries.

 * </li>

 * </ul>

 * 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.

 * </p>

 * <h3>Notification strategy</h3>

 * <p>
@@ -328,7 +314,6 @@ public abstract class AccessibilityService extends Service { 
     *     android:settingsActivity="foo.bar.TestBackActivity"

     *     android:canRetrieveWindowContent="true"

     *     android:canRequestTouchExplorationMode="true"

     *     android:canRequestEnhancedWebAccessibility="true"

     *     . . .

     * /&gt;</pre>

     */
@@ -528,6 +513,14 @@ public abstract class AccessibilityService extends Service { 
     * is currently touching or the window with input focus, if the user is not

     * touching any window.

     * <p>

     * The currently active window is defined as the window that most recently fired one

     * of the following events:

     * {@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED},

     * {@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER},

     * {@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}.

     * In other words, the last window shown that also has input focus.

     * </p>

     * <p>

     * <strong>Note:</strong> In order to access the root node your service has

     * to declare the capability to retrieve window content by setting the

     * {@link android.R.styleable#AccessibilityService_canRetrieveWindowContent}
@@ -541,8 +534,8 @@ public abstract class AccessibilityService extends Service { 
    }



    /**

     * This method allows accessibility service turn itself off

     * and the service will become disabled from the Settings.

     * Disables the service. After calling this method, the service will be disabled and settings

     * will show that it is turned off.

     */

    public final void disableSelf() {

        final IAccessibilityServiceConnection connection =

core/java/android/view/WindowManager.java

+2 −2
Original line number Diff line number Diff line
@@ -589,14 +589,14 @@ public interface WindowManager extends ViewManager { 
        public static final int TYPE_VOICE_INTERACTION = FIRST_SYSTEM_WINDOW+31;



        /**

         * Window type: Windows that are overlaid <em>only</em> by an {@link

         * Window type: Windows that are overlaid <em>only</em> by a connected {@link

         * android.accessibilityservice.AccessibilityService} for interception of

         * user interactions without changing the windows an accessibility service

         * can introspect. In particular, an accessibility service can introspect

         * only windows that a sighted user can interact with which is they can touch

         * these windows or can type into these windows. For example, if there

         * is a full screen accessibility overlay that is touchable, the windows

         * below it will be introspectable by an accessibility service regardless

         * below it will be introspectable by an accessibility service even though

         * they are covered by a touchable window.

         */

        public static final int TYPE_ACCESSIBILITY_OVERLAY = FIRST_SYSTEM_WINDOW+32;

core/java/android/view/accessibility/AccessibilityNodeInfo.java

+19 −7
Original line number Diff line number Diff line
@@ -38,8 +38,8 @@ import java.util.List; 
/**

 * This class represents a node of the window content as well as actions that

 * can be requested from its source. From the point of view of an

 * {@link android.accessibilityservice.AccessibilityService} a window content is

 * presented as tree of accessibility node info which may or may not map one-to-one

 * {@link android.accessibilityservice.AccessibilityService} a window's content is

 * presented as a tree of accessibility node infos, which may or may not map one-to-one

 * to the view hierarchy. In other words, a custom view is free to report itself as

 * a tree of accessibility node info.

 * </p>
@@ -50,7 +50,7 @@ import java.util.List; 
 * <p>

 * Please refer to {@link android.accessibilityservice.AccessibilityService} for

 * details about how to obtain a handle to window content as a tree of accessibility

 * node info as well as familiarizing with the security model.

 * node info as well as details about the security model.

 * </p>

 * <div class="special reference">

 * <h3>Developer Guides</h3>
@@ -2422,18 +2422,30 @@ public class AccessibilityNodeInfo implements Parcelable { 
    }



    /**

     * Gets the text selection start.

     * Gets the text selection start or the cursor position.

     * <p>

     * If no text is selected, both this method and

     * {@link AccessibilityNodeInfo#getTextSelectionEnd()} return the same value:

     * the current location of the cursor.

     * </p>

     *

     * @return The text selection start if there is selection or -1.

     * @return The text selection start, the cursor location if there is no selection, or -1 if

     *         there is no text selection and no cursor.

     */

    public int getTextSelectionStart() {

        return mTextSelectionStart;

    }



    /**

     * Gets the text selection end.

     * Gets the text selection end if text is selected.

     * <p>

     * If no text is selected, both this method and

     * {@link AccessibilityNodeInfo#getTextSelectionStart()} return the same value:

     * the current location of the cursor.

     * </p>

     *

     * @return The text selection end if there is selection or -1.

     * @return The text selection end, the cursor location if there is no selection, or -1 if

     *         there is no text selection and no cursor.

     */

    public int getTextSelectionEnd() {

        return mTextSelectionEnd;