1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.view; 18 19 import android.annotation.UnsupportedAppUsage; 20 import android.content.Context; 21 import android.util.Log; 22 23 /** 24 * An ActionProvider defines rich menu interaction in a single component. 25 * ActionProvider can generate action views for use in the action bar, 26 * dynamically populate submenus of a MenuItem, and handle default menu 27 * item invocations. 28 * 29 * <p>An ActionProvider can be optionally specified for a {@link MenuItem} and will be 30 * responsible for creating the action view that appears in the {@link android.app.ActionBar} 31 * in place of a simple button in the bar. When the menu item is presented in a way that 32 * does not allow custom action views, (e.g. in an overflow menu,) the ActionProvider 33 * can perform a default action.</p> 34 * 35 * <p>There are two ways to use an action provider: 36 * <ul> 37 * <li> 38 * Set the action provider on a {@link MenuItem} directly by calling 39 * {@link MenuItem#setActionProvider(ActionProvider)}. 40 * </li> 41 * <li> 42 * Declare the action provider in an XML menu resource. For example: 43 * <pre> 44 * <code> 45 * <item android:id="@+id/my_menu_item" 46 * android:title="Title" 47 * android:icon="@drawable/my_menu_item_icon" 48 * android:showAsAction="ifRoom" 49 * android:actionProviderClass="foo.bar.SomeActionProvider" /> 50 * </code> 51 * </pre> 52 * </li> 53 * </ul> 54 * </p> 55 * 56 * @see MenuItem#setActionProvider(ActionProvider) 57 * @see MenuItem#getActionProvider() 58 */ 59 public abstract class ActionProvider { 60 private static final String TAG = "ActionProvider"; 61 private SubUiVisibilityListener mSubUiVisibilityListener; 62 private VisibilityListener mVisibilityListener; 63 64 /** 65 * Creates a new instance. ActionProvider classes should always implement a 66 * constructor that takes a single Context parameter for inflating from menu XML. 67 * 68 * @param context Context for accessing resources. 69 */ ActionProvider(Context context)70 public ActionProvider(Context context) { 71 } 72 73 /** 74 * Factory method called by the Android framework to create new action views. 75 * 76 * <p>This method has been deprecated in favor of {@link #onCreateActionView(MenuItem)}. 77 * Newer apps that wish to support platform versions prior to API 16 should also 78 * implement this method to return a valid action view.</p> 79 * 80 * @return A new action view. 81 * 82 * @deprecated use {@link #onCreateActionView(MenuItem)} 83 */ 84 @Deprecated onCreateActionView()85 public abstract View onCreateActionView(); 86 87 /** 88 * Factory method called by the Android framework to create new action views. 89 * This method returns a new action view for the given MenuItem. 90 * 91 * <p>If your ActionProvider implementation overrides the deprecated no-argument overload 92 * {@link #onCreateActionView()}, overriding this method for devices running API 16 or later 93 * is recommended but optional. The default implementation calls {@link #onCreateActionView()} 94 * for compatibility with applications written for older platform versions.</p> 95 * 96 * @param forItem MenuItem to create the action view for 97 * @return the new action view 98 */ onCreateActionView(MenuItem forItem)99 public View onCreateActionView(MenuItem forItem) { 100 return onCreateActionView(); 101 } 102 103 /** 104 * The result of this method determines whether or not {@link #isVisible()} will be used 105 * by the {@link MenuItem} this ActionProvider is bound to help determine its visibility. 106 * 107 * @return true if this ActionProvider overrides the visibility of the MenuItem 108 * it is bound to, false otherwise. The default implementation returns false. 109 * @see #isVisible() 110 */ overridesItemVisibility()111 public boolean overridesItemVisibility() { 112 return false; 113 } 114 115 /** 116 * If {@link #overridesItemVisibility()} returns true, the return value of this method 117 * will help determine the visibility of the {@link MenuItem} this ActionProvider is bound to. 118 * 119 * <p>If the MenuItem's visibility is explicitly set to false by the application, 120 * the MenuItem will not be shown, even if this method returns true.</p> 121 * 122 * @return true if the MenuItem this ActionProvider is bound to is visible, false if 123 * it is invisible. The default implementation returns true. 124 */ isVisible()125 public boolean isVisible() { 126 return true; 127 } 128 129 /** 130 * If this ActionProvider is associated with an item in a menu, 131 * refresh the visibility of the item based on {@link #overridesItemVisibility()} and 132 * {@link #isVisible()}. If {@link #overridesItemVisibility()} returns false, this call 133 * will have no effect. 134 */ refreshVisibility()135 public void refreshVisibility() { 136 if (mVisibilityListener != null && overridesItemVisibility()) { 137 mVisibilityListener.onActionProviderVisibilityChanged(isVisible()); 138 } 139 } 140 141 /** 142 * Performs an optional default action. 143 * <p> 144 * For the case of an action provider placed in a menu item not shown as an action this 145 * method is invoked if previous callbacks for processing menu selection has handled 146 * the event. 147 * </p> 148 * <p> 149 * A menu item selection is processed in the following order: 150 * <ul> 151 * <li> 152 * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick 153 * MenuItem.OnMenuItemClickListener.onMenuItemClick}. 154 * </li> 155 * <li> 156 * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem) 157 * Activity.onOptionsItemSelected(MenuItem)} 158 * </li> 159 * <li> 160 * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem) 161 * Fragment.onOptionsItemSelected(MenuItem)} 162 * </li> 163 * <li> 164 * Launching the {@link android.content.Intent} set via 165 * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)} 166 * </li> 167 * <li> 168 * Invoking this method. 169 * </li> 170 * </ul> 171 * </p> 172 * <p> 173 * The default implementation does not perform any action and returns false. 174 * </p> 175 */ onPerformDefaultAction()176 public boolean onPerformDefaultAction() { 177 return false; 178 } 179 180 /** 181 * Determines if this ActionProvider has a submenu associated with it. 182 * 183 * <p>Associated submenus will be shown when an action view is not. This 184 * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)} 185 * after the call to {@link #onPerformDefaultAction()} and before a submenu is 186 * displayed to the user. 187 * 188 * @return true if the item backed by this provider should have an associated submenu 189 */ hasSubMenu()190 public boolean hasSubMenu() { 191 return false; 192 } 193 194 /** 195 * Called to prepare an associated submenu for the menu item backed by this ActionProvider. 196 * 197 * <p>if {@link #hasSubMenu()} returns true, this method will be called when the 198 * menu item is selected to prepare the submenu for presentation to the user. Apps 199 * may use this to create or alter submenu content right before display. 200 * 201 * @param subMenu Submenu that will be displayed 202 */ onPrepareSubMenu(SubMenu subMenu)203 public void onPrepareSubMenu(SubMenu subMenu) { 204 } 205 206 /** 207 * Notify the system that the visibility of an action view's sub-UI such as 208 * an anchored popup has changed. This will affect how other system 209 * visibility notifications occur. 210 * 211 * @hide Pending future API approval 212 */ subUiVisibilityChanged(boolean isVisible)213 public void subUiVisibilityChanged(boolean isVisible) { 214 if (mSubUiVisibilityListener != null) { 215 mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible); 216 } 217 } 218 219 /** 220 * @hide Internal use only 221 */ 222 @UnsupportedAppUsage setSubUiVisibilityListener(SubUiVisibilityListener listener)223 public void setSubUiVisibilityListener(SubUiVisibilityListener listener) { 224 mSubUiVisibilityListener = listener; 225 } 226 227 /** 228 * Set a listener to be notified when this ActionProvider's overridden visibility changes. 229 * This should only be used by MenuItem implementations. 230 * 231 * @param listener listener to set 232 */ setVisibilityListener(VisibilityListener listener)233 public void setVisibilityListener(VisibilityListener listener) { 234 if (mVisibilityListener != null) { 235 Log.w(TAG, "setVisibilityListener: Setting a new ActionProvider.VisibilityListener " + 236 "when one is already set. Are you reusing this " + getClass().getSimpleName() + 237 " instance while it is still in use somewhere else?"); 238 } 239 mVisibilityListener = listener; 240 } 241 242 /** 243 * @hide 244 */ 245 @UnsupportedAppUsage reset()246 public void reset() { 247 mVisibilityListener = null; 248 mSubUiVisibilityListener = null; 249 } 250 251 /** 252 * @hide Internal use only 253 */ 254 public interface SubUiVisibilityListener { onSubUiVisibilityChanged(boolean isVisible)255 public void onSubUiVisibilityChanged(boolean isVisible); 256 } 257 258 /** 259 * Listens to changes in visibility as reported by {@link ActionProvider#refreshVisibility()}. 260 * 261 * @see ActionProvider#overridesItemVisibility() 262 * @see ActionProvider#isVisible() 263 */ 264 public interface VisibilityListener { onActionProviderVisibilityChanged(boolean isVisible)265 public void onActionProviderVisibilityChanged(boolean isVisible); 266 } 267 } 268