Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: a couple notes for a11y methods in View and cleanup to the A11y service HTML to be semantically correct and thus improve its accessibility :)" into ics-mr0

Browse Source
This commit is contained in:
Scott Main
2011-10-14 17:19:17 -07:00
committed by Android (Google) Code Review
parent b227cce316 b303d8381d
commit f755a2e8aa
3 changed files with 80 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
core/java/android/accessibilityservice/AccessibilityService.java
View File

@@ -32,11 +32,9 @@ import android.view.accessibility.AccessibilityNodeInfo;
* 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
* of the active window. Development of an accessibility service requires extends this
* class and implements its abstract methods.
* <p>
* <strong>Lifecycle</strong>
* </p>
* of the active window. Development of an accessibility service requires extending this
* class and implementing its abstract methods.
* <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
@@ -45,30 +43,20 @@ import android.view.accessibility.AccessibilityNodeInfo;
* calls {@link AccessibilityService#onServiceConnected()}. This method can be
* overriden by clients that want to perform post binding setup.
* </p>
* <p>
* <strong>Declaration</strong>
* </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. Following is an example declaration:
* </p>
* <p>
* <code>
* <pre>
* &lt;service android:name=".MyAccessibilityService"&gt;
* <pre> &lt;service android:name=".MyAccessibilityService"&gt;
* &lt;intent-filter&gt;
* &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
* &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
* &lt;/intent-filter&gt;
* . . .
* &lt;/service&gt;
* </pre>
* </code>
* </p>
* <p>
* <strong>Configuration</strong>
* </p>
* &lt;/service&gt;</pre>
* <h3>Configuration</h3>
* <p>
* 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,
@@ -81,30 +69,24 @@ import android.view.accessibility.AccessibilityNodeInfo;
* <li>
* Providing a {@link #SERVICE_META_DATA meta-data} entry in the manifest when declaring
* the service. A service declaration with a meta-data tag is presented below:
* <p>
* <code>
* <pre>
* &lt;service android:name=".MyAccessibilityService"&gt;
* <pre> &lt;service android:name=".MyAccessibilityService"&gt;
* &lt;intent-filter&gt;
* &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
* &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
* &lt;/intent-filter&gt;
* &lt;meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibilityservice" /&gt;
* &lt;/service&gt;
* </pre>
* </code>
* </p>
* <p>
* <strong>Note:</strong>This approach enables setting all properties.
* &lt;/service&gt;</pre>
* <p class="note">
* <strong>Note:</strong> This approach enables setting all properties.
* </p>
* <p>
* For more details refer to {@link #SERVICE_META_DATA} and
* <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>..
* <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>.
* </p>
* </li>
* <li>
* Calling {@link AccessibilityService#setServiceInfo(AccessibilityServiceInfo)}. Note
* that this method can be called any time to dynamically change the service configuration.
* <p>
* <p class="note">
* <strong>Note:</strong> This approach enables setting only dynamically configurable properties:
* {@link AccessibilityServiceInfo#eventTypes},
* {@link AccessibilityServiceInfo#feedbackType},
@@ -117,9 +99,7 @@ import android.view.accessibility.AccessibilityNodeInfo;
* </p>
* </li>
* </ul>
* <p>
* <strong>Retrieving window content</strong>
* </p>
* <h3>Retrieving window content</h3>
* <p>
* An 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
@@ -144,8 +124,8 @@ import android.view.accessibility.AccessibilityNodeInfo;
* this method will return an {@link AccessibilityNodeInfo} that can be used to traverse the
* window content which represented as a tree of such objects.
* </p>
* <p>
* <strong>Note</strong>An accessibility service may have requested to be notified for
* <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>
@@ -158,15 +138,13 @@ import android.view.accessibility.AccessibilityNodeInfo;
* <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 event adopting the strategy
* 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>
* </p>
* <p>
* <b>Notification strategy</b>
* </p>
* <h3>Notification strategy</h3>
* <p>
* For each feedback type only one accessibility service is notified. Services are notified
* in the order of registration. Hence, if two services are registered for the same
@@ -178,40 +156,39 @@ import android.view.accessibility.AccessibilityNodeInfo;
* well with most applications to coexist with "polished" ones that are targeted for
* specific applications.
* </p>
* <p>
* <b>Event types</b>
* </p>
* {@link AccessibilityEvent#TYPE_VIEW_CLICKED}
* {@link AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}
* {@link AccessibilityEvent#TYPE_VIEW_FOCUSED}
* {@link AccessibilityEvent#TYPE_VIEW_SELECTED}
* {@link AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}
* {@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED}
* {@link AccessibilityEvent#TYPE_NOTIFICATION_STATE_CHANGED}
* {@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_START}
* {@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_END}
* {@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}
* {@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}
* {@link AccessibilityEvent#TYPE_VIEW_SCROLLED}
* {@link AccessibilityEvent#TYPE_VIEW_TEXT_SELECTION_CHANGED}
* {@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED}
* <p>
* <b>Feedback types</b>
* <p>
* {@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}
* {@link AccessibilityServiceInfo#FEEDBACK_HAPTIC}
* {@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}
* {@link AccessibilityServiceInfo#FEEDBACK_VISUAL}
* {@link AccessibilityServiceInfo#FEEDBACK_GENERIC}
*
* @see AccessibilityEvent
* @see AccessibilityServiceInfo
* @see android.view.accessibility.AccessibilityManager
*
* <p class="note">
* <strong>Note:</strong> 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 generation has settled down.</p>
* <h3>Event types</h3>
* <ul>
* <li>{@link AccessibilityEvent#TYPE_VIEW_CLICKED}
* <li>{@link AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}
* <li>{@link AccessibilityEvent#TYPE_VIEW_FOCUSED}
* <li>{@link AccessibilityEvent#TYPE_VIEW_SELECTED}
* <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}
* <li>{@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED}
* <li>{@link AccessibilityEvent#TYPE_NOTIFICATION_STATE_CHANGED}
* <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_START}
* <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_END}
* <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}
* <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}
* <li>{@link AccessibilityEvent#TYPE_VIEW_SCROLLED}
* <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_SELECTION_CHANGED}
* <li>{@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED}
* </ul>
* <h3>Feedback types</h3>
* <ul>
* <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}
* <li>{@link AccessibilityServiceInfo#FEEDBACK_HAPTIC}
* <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}
* <li>{@link AccessibilityServiceInfo#FEEDBACK_VISUAL}
* <li>{@link AccessibilityServiceInfo#FEEDBACK_GENERIC}
* </ul>
* @see AccessibilityEvent
* @see AccessibilityServiceInfo
* @see android.view.accessibility.AccessibilityManager
*/
public abstract class AccessibilityService extends Service {
/**
@@ -225,10 +202,7 @@ public abstract class AccessibilityService extends Service {
* about itself. This meta-data must reference an XML resource containing an
* <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>
* tag. This is a a sample XML file configuring an accessibility service:
* <p>
* <code>
* <pre>
* &lt;accessibility-service
* <pre> &lt;accessibility-service
* android:accessibilityEventTypes="typeViewClicked|typeViewFocused"
* android:packageNames="foo.bar, foo.baz"
* android:accessibilityFeedbackType="feedbackSpoken"
@@ -237,10 +211,7 @@ public abstract class AccessibilityService extends Service {
* android:settingsActivity="foo.bar.TestBackActivity"
* android:canRetrieveWindowContent="true"
* . . .
* /&gt;
* </pre>
* </code>
* </p>
* /&gt;</pre>
*/
public static final String SERVICE_META_DATA = "android.accessibilityservice";

42
core/java/android/view/View.java
View File

@@ -3830,7 +3830,10 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal
* responsible for handling this call.
* </p>
*
* @param eventType The type of the event to send.
* @param eventType The type of the event to send, as defined by several types from
* {@link android.view.accessibility.AccessibilityEvent}, such as
* {@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED} or
* {@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}.
*
* @see #onInitializeAccessibilityEvent(AccessibilityEvent)
* @see #dispatchPopulateAccessibilityEvent(AccessibilityEvent)
@@ -3943,27 +3946,28 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal
/**
* Called from {@link #dispatchPopulateAccessibilityEvent(AccessibilityEvent)}
* giving a chance to this View to populate the accessibility event with its
* text content. While the implementation is free to modify other event
* attributes this should be performed in
* text content. While this method is free to modify event
* attributes other than text content, doing so should normally be performed in
* {@link #onInitializeAccessibilityEvent(AccessibilityEvent)}.
* <p>
* Example: Adding formatted date string to an accessibility event in addition
* to the text added by the super implementation.
* </p><p><pre><code>
* public void onPopulateAccessibilityEvent(AccessibilityEvent event) {
* to the text added by the super implementation:
* <pre> public void onPopulateAccessibilityEvent(AccessibilityEvent event) {
* super.onPopulateAccessibilityEvent(event);
* final int flags = DateUtils.FORMAT_SHOW_DATE | DateUtils.FORMAT_SHOW_WEEKDAY;
* String selectedDateUtterance = DateUtils.formatDateTime(mContext,
* mCurrentDate.getTimeInMillis(), flags);
* event.getText().add(selectedDateUtterance);
* }
* </code></pre></p>
* }</pre>
* <p>
* If an {@link AccessibilityDelegate} has been specified via calling
* {@link #setAccessibilityDelegate(AccessibilityDelegate)} its
* {@link AccessibilityDelegate#onPopulateAccessibilityEvent(View, AccessibilityEvent)}
* is responsible for handling this call.
* </p>
* <p class="note"><strong>Note:</strong> Always call the super implementation before adding
* information to the event, in case the default implementation has basic information to add.
* </p>
*
* @param event The accessibility event which to populate.
*
@@ -3994,20 +3998,20 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal
* the event.
* <p>
* Example: Setting the password property of an event in addition
* to properties set by the super implementation.
* </p><p><pre><code>
* public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
* super.onInitializeAccessibilityEvent(event);
* event.setPassword(true);
* }
* </code></pre></p>
* to properties set by the super implementation:
* <pre> public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
* super.onInitializeAccessibilityEvent(event);
* event.setPassword(true);
* }</pre>
* <p>
* If an {@link AccessibilityDelegate} has been specified via calling
* {@link #setAccessibilityDelegate(AccessibilityDelegate)} its
* {@link AccessibilityDelegate#onInitializeAccessibilityEvent(View, AccessibilityEvent)}
* is responsible for handling this call.
* </p>
*
* <p class="note"><strong>Note:</strong> Always call the super implementation before adding
* information to the event, in case the default implementation has basic information to add.
* </p>
* @param event The event to initialize.
*
* @see #sendAccessibilityEvent(int)
@@ -6179,8 +6183,7 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal
* are delivered to the view under the pointer. All other generic motion events are
* delivered to the focused view.
* </p>
* <code>
* public boolean onGenericMotionEvent(MotionEvent event) {
* <pre> public boolean onGenericMotionEvent(MotionEvent event) {
* if ((event.getSource() &amp; InputDevice.SOURCE_CLASS_JOYSTICK) != 0) {
* if (event.getAction() == MotionEvent.ACTION_MOVE) {
* // process the joystick movement...
@@ -6198,8 +6201,7 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal
* }
* }
* return super.onGenericMotionEvent(event);
* }
* </code>
* }</pre>
*
* @param event The generic motion event being processed.
* @return True if the event was handled, false otherwise.

11
core/java/android/view/accessibility/AccessibilityManager.java
View File

@@ -49,10 +49,8 @@ import java.util.concurrent.CopyOnWriteArrayList;
* </p>
* <p>
* <code>
* <pre>
* AccessibilityManager accessibilityManager =
* (AccessibilityManager) context.getSystemService(Context.ACCESSIBILITY_SERVICE);
* </pre>
* <pre>AccessibilityManager accessibilityManager =
* (AccessibilityManager) context.getSystemService(Context.ACCESSIBILITY_SERVICE);</pre>
* </code>
* </p>
*
@@ -91,7 +89,10 @@ public final class AccessibilityManager {
new CopyOnWriteArrayList<AccessibilityStateChangeListener>();
/**
* Listener for the accessibility state.
* Listener for the system accessibility state. To listen for changes to the accessibility
* state on the device, implement this interface and register it with the system by
* calling {@link AccessibilityManager#addAccessibilityStateChangeListener
* addAccessibilityStateChangeListener()}.
*/
public interface AccessibilityStateChangeListener {