From 827ae4da93aaf8818ace709afb57a4bd38547ad8 Mon Sep 17 00:00:00 2001
From: Sally Yuen <sallyyuen@google.com>
Date: Fri, 2 Sep 2022 23:51:11 +0000
Subject: [PATCH] Add to AccessibilityEvent#TYPE_ANNOUNCEMENT with suggestion
 to avoid using it.

Bug: 244788390
Test: n/a
Change-Id: I1a9300fb70e0e9b35dd7f1b07686cad00c2ac9a2
---
 core/java/android/view/View.java                     | 12 ++++++++++++
 .../view/accessibility/AccessibilityEvent.java       |  4 ++++
 2 files changed, 16 insertions(+)

diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 49d9e67ce51df..3c5f3f76c3df8 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -8457,6 +8457,18 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * accurately supplying the semantics of their UI.
      * They should not need to specify what exactly is announced to users.
      *
+     * <p>
+     * In general, only announce transitions and don’t generate a confirmation message for simple
+     * actions like a button press. Label your controls concisely and precisely instead, and for
+     * significant UI changes like window changes, use
+     * {@link android.app.Activity#setTitle(CharSequence)} and
+     * {@link View#setAccessibilityPaneTitle(CharSequence)}.
+     *
+     * <p>
+     * Use {@link View#setAccessibilityLiveRegion(int)} to inform the user of changes to critical
+     * views within the user interface. These should still be used sparingly as they may generate
+     * announcements every time a View is updated.
+     *
      * @param text The announcement text.
      */
     public void announceForAccessibility(CharSequence text) {
diff --git a/core/java/android/view/accessibility/AccessibilityEvent.java b/core/java/android/view/accessibility/AccessibilityEvent.java
index b0cf504ec568b..a52a99bec5007 100644
--- a/core/java/android/view/accessibility/AccessibilityEvent.java
+++ b/core/java/android/view/accessibility/AccessibilityEvent.java
@@ -24,6 +24,7 @@ import android.os.Parcel;
 import android.os.Parcelable;
 import android.text.TextUtils;
 import android.util.Log;
+import android.view.View;
 
 import com.android.internal.util.BitUtils;
 
@@ -519,6 +520,9 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
 
     /**
      * Represents the event of an application making an announcement.
+     * <p>
+     * In general, follow the practices described in
+     * {@link View#announceForAccessibility(CharSequence)}.
      */
     public static final int TYPE_ANNOUNCEMENT = 0x00004000;