JB API cleanup; ActionMode and View docs

Bugs 6435315, 6434937

Add ActionMode#getTitleOptionalHint() and extend documentation for
View#hasTransientState/setHasTransientState

Change-Id: I2049fb79864c33b34e3bbd13df32861e308c99ad

Author: adamp

api/current.txt

@@ -22532,6 +22532,7 @@ package android.view {
     method public abstract java.lang.CharSequence getSubtitle();
     method public java.lang.Object getTag();
     method public abstract java.lang.CharSequence getTitle();
+    method public boolean getTitleOptionalHint();
     method public abstract void invalidate();
     method public boolean isTitleOptional();
     method public abstract void setCustomView(android.view.View);

core/java/android/view/ActionMode.java

@@ -30,6 +30,7 @@
  */
 public abstract class ActionMode {
     private Object mTag;
+    private boolean mTitleOptionalHint;
 
     /**
      * Set a tag object associated with this ActionMode.
@@ -119,6 +120,18 @@ public Object getTag() {
      * @param titleOptional true if the title only presents optional information.
      */
     public void setTitleOptionalHint(boolean titleOptional) {
+        mTitleOptionalHint = titleOptional;
+    }
+
+    /**
+     * @return true if this action mode has been given a hint to consider the
+     *         title/subtitle display to be optional.
+     *
+     * @see #setTitleOptionalHint(boolean)
+     * @see #isTitleOptional()
+     */
+    public boolean getTitleOptionalHint() {
+        return mTitleOptionalHint;
     }
 
     /**

core/java/android/view/View.java

@@ -5423,6 +5423,11 @@ public boolean isLayoutRtl() {
      * app should not need to concern itself with saving and restoring, but that
      * the framework should take special note to preserve when possible.
      *
+     * <p>A view with transient state cannot be trivially rebound from an external
+     * data source, such as an adapter binding item views in a list. This may be
+     * because the view is performing an animation, tracking user selection
+     * of content, or similar.</p>
+     *
      * @return true if the view has transient state
      */
     @ViewDebug.ExportedProperty(category = "layout")
@@ -5436,6 +5441,11 @@ public boolean hasTransientState() {
      * so every call to setHasTransientState(true) should be paired with a later call
      * to setHasTransientState(false).
      *
+     * <p>A view with transient state cannot be trivially rebound from an external
+     * data source, such as an adapter binding item views in a list. This may be
+     * because the view is performing an animation, tracking user selection
+     * of content, or similar.</p>
+     *
      * @param hasTransientState true if this view has transient state
      */
     public void setHasTransientState(boolean hasTransientState) {

core/java/com/android/internal/app/ActionBarImpl.java

@@ -817,6 +817,7 @@ public CharSequence getSubtitle() {
 
         @Override
         public void setTitleOptionalHint(boolean titleOptional) {
+            super.setTitleOptionalHint(titleOptional);
             mContextView.setTitleOptional(titleOptional);
         }
 

core/java/com/android/internal/view/StandaloneActionMode.java

@@ -73,6 +73,7 @@ public void setSubtitle(int resId) {
 
     @Override
     public void setTitleOptionalHint(boolean titleOptional) {
+        super.setTitleOptionalHint(titleOptional);
         mContextView.setTitleOptional(titleOptional);
     }