Nicer API for disabling/enabling the home/up button in action bars.

Have an explicit call for enabling the home/up button. Auto-enable it
if the app targets < ICS to preserve Honeycomb behavior. Auto-enable
it if the app shows home as up.

This prevents unwanted touch/focus feedback on the home button when
the app hasn't wired it up to do anything useful.

Change-Id: Icfe95ab5a11b3998bca08b0fbbfe1bf6c3c89b5d

diff --git a/api/current.txt b/api/current.txt
index 9a62297..e636ae7 100644 (file)
--- a/api/current.txt
+++ b/api/current.txt
@@ -2256,7 +2256,6 @@ package android.app {
     method public abstract void setCustomView(android.view.View);
     method public abstract void setCustomView(android.view.View, android.app.ActionBar.LayoutParams);
     method public abstract void setCustomView(int);
-    method public abstract void setDisplayDisableHomeEnabled(boolean);
     method public abstract void setDisplayHomeAsUpEnabled(boolean);
     method public abstract void setDisplayOptions(int);
     method public abstract void setDisplayOptions(int, int);
@@ -2264,6 +2263,7 @@ package android.app {
     method public abstract void setDisplayShowHomeEnabled(boolean);
     method public abstract void setDisplayShowTitleEnabled(boolean);
     method public abstract void setDisplayUseLogoEnabled(boolean);
+    method public abstract void setHomeButtonEnabled(boolean);
     method public abstract void setIcon(int);
     method public abstract void setIcon(android.graphics.drawable.Drawable);
     method public abstract void setListNavigationCallbacks(android.widget.SpinnerAdapter, android.app.ActionBar.OnNavigationListener);
@@ -2276,7 +2276,6 @@ package android.app {
     method public abstract void setTitle(java.lang.CharSequence);
     method public abstract void setTitle(int);
     method public abstract void show();
-    field public static final int DISPLAY_DISABLE_HOME = 32; // 0x20
     field public static final int DISPLAY_HOME_AS_UP = 4; // 0x4
     field public static final int DISPLAY_SHOW_CUSTOM = 16; // 0x10
     field public static final int DISPLAY_SHOW_HOME = 2; // 0x2

diff --git a/core/java/android/app/ActionBar.java b/core/java/android/app/ActionBar.java
index 3ec5edb..36940c2 100644 (file)
--- a/core/java/android/app/ActionBar.java
+++ b/core/java/android/app/ActionBar.java
@@ -81,6 +81,9 @@ public abstract class ActionBar {
      * Set this flag if selecting the 'home' button in the action bar to return
      * up by a single level in your UI rather than back to the top level or front page.
      *
+     * <p>Setting this option will implicitly enable interaction with the home/up
+     * button. See {@link #setHomeButtonEnabled(boolean)}.
+     *
      * @see #setDisplayOptions(int)
      * @see #setDisplayOptions(int, int)
      */
@@ -107,18 +110,6 @@ public abstract class ActionBar {
     public static final int DISPLAY_SHOW_CUSTOM = 0x10;
 
     /**
-     * Disable the 'home' element. This may be combined with
-     * {@link #DISPLAY_SHOW_HOME} to create a non-focusable/non-clickable
-     * 'home' element. Useful for a level of your app's navigation hierarchy
-     * where clicking 'home' doesn't do anything.
-     *
-     * @see #setDisplayOptions(int)
-     * @see #setDisplayOptions(int, int)
-     * @see #setDisplayDisableHomeEnabled(boolean)
-     */
-    public static final int DISPLAY_DISABLE_HOME = 0x20;
-
-    /**
      * Set the action bar into custom navigation mode, supplying a view
      * for custom navigation.
      *
@@ -405,21 +396,6 @@ public abstract class ActionBar {
     public abstract void setDisplayShowCustomEnabled(boolean showCustom);
 
     /**
-     * Set whether the 'home' affordance on the action bar should be disabled.
-     * If set, the 'home' element will not be focusable or clickable, useful if
-     * the user is at the top level of the app's navigation hierarchy.
-     *
-     * <p>To set several display options at once, see the setDisplayOptions methods.
-     *
-     * @param disableHome true to disable the 'home' element.
-     *
-     * @see #setDisplayOptions(int)
-     * @see #setDisplayOptions(int, int)
-     * @see #DISPLAY_DISABLE_HOME
-     */
-    public abstract void setDisplayDisableHomeEnabled(boolean disableHome);
-
-    /**
      * Set the ActionBar's background.
      * 
      * @param d Background drawable
@@ -632,6 +608,22 @@ public abstract class ActionBar {
     public abstract void removeOnMenuVisibilityListener(OnMenuVisibilityListener listener);
 
     /**
+     * Enable or disable the "home" button in the corner of the action bar. (Note that this
+     * is the application home/up affordance on the action bar, not the systemwide home
+     * button.)
+     *
+     * <p>This defaults to true for packages targeting &lt; API 14. For packages targeting
+     * API 14 or greater, the application should call this method to enable interaction
+     * with the home/up affordance.
+     *
+     * <p>Setting the {@link #DISPLAY_HOME_AS_UP} display option will automatically enable
+     * the home button.
+     *
+     * @param enabled true to enable the home button, false to disable the home button.
+     */
+    public abstract void setHomeButtonEnabled(boolean enabled);
+
+    /**
      * Listener interface for ActionBar navigation events.
      */
     public interface OnNavigationListener {

diff --git a/core/java/com/android/internal/app/ActionBarImpl.java b/core/java/com/android/internal/app/ActionBarImpl.java
index 519acf5..243c605 100644 (file)
--- a/core/java/com/android/internal/app/ActionBarImpl.java
+++ b/core/java/com/android/internal/app/ActionBarImpl.java
@@ -36,6 +36,7 @@ import android.app.FragmentTransaction;
 import android.content.Context;
 import android.content.res.Configuration;
 import android.graphics.drawable.Drawable;
+import android.os.Build;
 import android.os.Handler;
 import android.view.ActionMode;
 import android.view.LayoutInflater;
@@ -155,6 +156,13 @@ public class ActionBarImpl extends ActionBar {
                 CONTEXT_DISPLAY_SPLIT : CONTEXT_DISPLAY_NORMAL;
 
         mContentHeight = mActionView.getContentHeight();
+
+        // Older apps get the home button interaction enabled by default.
+        // Newer apps need to enable it explicitly.
+        if (mContext.getApplicationInfo().targetSdkVersion <
+                Build.VERSION_CODES.ICE_CREAM_SANDWICH) {
+            setHomeButtonEnabled(true);
+        }
     }
 
     public void onConfigurationChanged(Configuration newConfig) {
@@ -266,8 +274,8 @@ public class ActionBarImpl extends ActionBar {
     }
 
     @Override
-    public void setDisplayDisableHomeEnabled(boolean disableHome) {
-        setDisplayOptions(disableHome ? DISPLAY_DISABLE_HOME : 0, DISPLAY_DISABLE_HOME);
+    public void setHomeButtonEnabled(boolean enable) {
+        mActionView.setHomeButtonEnabled(enable);
     }
 
     @Override

diff --git a/core/java/com/android/internal/widget/ActionBarView.java b/core/java/com/android/internal/widget/ActionBarView.java
index 595753a..58043c9 100644 (file)
--- a/core/java/com/android/internal/widget/ActionBarView.java
+++ b/core/java/com/android/internal/widget/ActionBarView.java
@@ -434,22 +434,40 @@ public class ActionBarView extends AbsActionBarView {
         }
     }
 
+    public void setHomeButtonEnabled(boolean enable) {
+        mHomeLayout.setEnabled(enable);
+        // Make sure the home button has an accurate content description for accessibility.
+        if (!enable) {
+            mHomeLayout.setContentDescription(null);
+        } else if ((mDisplayOptions & ActionBar.DISPLAY_HOME_AS_UP) != 0) {
+            mHomeLayout.setContentDescription(mContext.getResources().getText(
+                    R.string.action_bar_up_description));
+        } else {
+            mHomeLayout.setContentDescription(mContext.getResources().getText(
+                    R.string.action_bar_home_description));
+        }
+    }
+
     public void setDisplayOptions(int options) {
         final int flagsChanged = options ^ mDisplayOptions;
         mDisplayOptions = options;
 
-        if ((flagsChanged & ActionBar.DISPLAY_DISABLE_HOME) != 0) {
-            final boolean disableHome = (options & ActionBar.DISPLAY_DISABLE_HOME) != 0;
-            mHomeLayout.setEnabled(!disableHome);
-        }
-
         if ((flagsChanged & DISPLAY_RELAYOUT_MASK) != 0) {
             final boolean showHome = (options & ActionBar.DISPLAY_SHOW_HOME) != 0;
             final int vis = showHome ? VISIBLE : GONE;
             mHomeLayout.setVisibility(vis);
 
             if ((flagsChanged & ActionBar.DISPLAY_HOME_AS_UP) != 0) {
-                mHomeLayout.setUp((options & ActionBar.DISPLAY_HOME_AS_UP) != 0);
+                final boolean setUp = (options & ActionBar.DISPLAY_HOME_AS_UP) != 0;
+                mHomeLayout.setUp(setUp);
+
+                // Showing home as up implicitly enables interaction with it.
+                // In honeycomb it was always enabled, so make this transition
+                // a bit easier for developers in the common case.
+                // (It would be silly to show it as up without responding to it.)
+                if (setUp) {
+                    setHomeButtonEnabled(true);
+                }
             }
 
             if ((flagsChanged & ActionBar.DISPLAY_USE_LOGO) != 0) {
@@ -487,7 +505,7 @@ public class ActionBarView extends AbsActionBarView {
         }
 
         // Make sure the home button has an accurate content description for accessibility.
-        if ((options & ActionBar.DISPLAY_DISABLE_HOME) != 0) {
+        if (!mHomeLayout.isEnabled()) {
             mHomeLayout.setContentDescription(null);
         } else if ((options & ActionBar.DISPLAY_HOME_AS_UP) != 0) {
             mHomeLayout.setContentDescription(mContext.getResources().getText(