From 51ab90cab1609cf0ddd2dfe5a660f020d823d4d5 Mon Sep 17 00:00:00 2001
From: Svetoslav Ganov <svetoslavganov@google.com>
Date: Fri, 9 Mar 2012 10:54:49 -0800
Subject: Adding an announcement type accessibility event and a method on View
 to announce.

1. The need for sending an accessibility event to announce a context change
   which does not cleanly fit into the existing UI transition UI events has
   come quite a few time in application development. To avoid retrofitting
   accessibility event types that do not semantically match the intent to
   just announce a short message this patch is adding specialized event type.
   Also a helper method on View is added to sheild developers from knowing
   how to construct and send such an event.

bug:5977979

Change-Id: Iaf5f620426f8616be67fbf243a02ad5b606c949b
---
 core/java/android/view/View.java                   | 18 ++++++++++++++
 .../view/accessibility/AccessibilityEvent.java     | 28 ++++++++++++++++++++++
 2 files changed, 46 insertions(+)

(limited to 'core/java')

diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index ecfca74..7cadee8 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -3934,6 +3934,24 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal
     }
 
     /**
+     * Convenience method for sending a {@link AccessibilityEvent#TYPE_ANNOUNCEMENT}
+     * {@link AccessibilityEvent} to make an announcement which is related to some
+     * sort of a context change for which none of the events representing UI transitions
+     * is a good fit. For example, announcing a new page in a book. If accessibility
+     * is not enabled this method does nothing.
+     *
+     * @param text The announcement text.
+     */
+    public void announceForAccessibility(CharSequence text) {
+        if (AccessibilityManager.getInstance(mContext).isEnabled()) {
+            AccessibilityEvent event = AccessibilityEvent.obtain(
+                    AccessibilityEvent.TYPE_ANNOUNCEMENT);
+            event.getText().add(text);
+            sendAccessibilityEventUnchecked(event);
+        }
+    }
+
+    /**
      * @see #sendAccessibilityEvent(int)
      *
      * Note: Called from the default {@link AccessibilityDelegate}.
diff --git a/core/java/android/view/accessibility/AccessibilityEvent.java b/core/java/android/view/accessibility/AccessibilityEvent.java
index 75b875a..58844fc 100644
--- a/core/java/android/view/accessibility/AccessibilityEvent.java
+++ b/core/java/android/view/accessibility/AccessibilityEvent.java
@@ -429,6 +429,26 @@ import java.util.List;
  * view.</br>
  * </p>
  * <p>
+ * <b>MISCELLANEOUS TYPES</b></br>
+ * </p>
+ * <p>
+ * <b>Announcement</b> - represents the event of an application making an
+ * announcement. Usually this announcement is related to some sort of a context
+ * change for which none of the events representing UI transitions is a good fit.
+ * For example, announcing a new page in a book.</br>
+ * <em>Type:</em> {@link #TYPE_ANNOUNCEMENT}</br>
+ * <em>Properties:</em></br>
+ * <ul>
+ *   <li>{@link #getEventType()} - The type of the event.</li>
+ *   <li>{@link #getSource()} - The source info (for registered clients).</li>
+ *   <li>{@link #getClassName()} - The class name of the source.</li>
+ *   <li>{@link #getPackageName()} - The package name of the source.</li>
+ *   <li>{@link #getEventTime()}  - The event time.</li>
+ *   <li>{@link #getText()} - The text of the announcement.</li>
+ *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
+ * </ul>
+ * </p>
+ * <p>
  * <b>Security note</b>
  * <p>
  * Since an event contains the text of its source privacy can be compromised by leaking
@@ -538,6 +558,11 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
     public static final int TYPE_VIEW_TEXT_SELECTION_CHANGED = 0x00002000;
 
     /**
+     * Represents the event of an application making an announcement.
+     */
+    public static final int TYPE_ANNOUNCEMENT = 0x00004000;
+
+    /**
      * Mask for {@link AccessibilityEvent} all types.
      *
      * @see #TYPE_VIEW_CLICKED
@@ -554,6 +579,7 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
      * @see #TYPE_WINDOW_CONTENT_CHANGED
      * @see #TYPE_VIEW_SCROLLED
      * @see #TYPE_VIEW_TEXT_SELECTION_CHANGED
+     * @see #TYPE_ANNOUNCEMENT
      */
     public static final int TYPES_ALL_MASK = 0xFFFFFFFF;
 
@@ -984,6 +1010,8 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
                 return "TYPE_VIEW_TEXT_SELECTION_CHANGED";
             case TYPE_VIEW_SCROLLED:
                 return "TYPE_VIEW_SCROLLED";
+            case TYPE_ANNOUNCEMENT:
+                return "TYPE_ANNOUNCEMENT";
             default:
                 return null;
         }
-- 
cgit v1.1