ActionProvider.java revision bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17f
1bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell/* 2bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Copyright (C) 2011 The Android Open Source Project 3bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 4bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Licensed under the Apache License, Version 2.0 (the "License"); 5bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * you may not use this file except in compliance with the License. 6bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * You may obtain a copy of the License at 7bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 8bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * http://www.apache.org/licenses/LICENSE-2.0 9bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 10bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Unless required by applicable law or agreed to in writing, software 11bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * distributed under the License is distributed on an "AS IS" BASIS, 12bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * See the License for the specific language governing permissions and 14bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * limitations under the License. 15bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 16bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 17bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellpackage android.support.appcompat.view; 18bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 19bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellimport android.content.Context; 20bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellimport android.view.SubMenu; 21bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellimport android.view.View; 22bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 23bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell/** 24bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * This class is a mediator for accomplishing a given task, for example sharing a file. 25bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * It is responsible for creating a view that performs an action that accomplishes the task. 26bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * This class also implements other functions such a performing a default action. 27bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <p> 28bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * An ActionProvider can be optionally specified for a {@link MenuItem} and in such a 29bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * case it will be responsible for creating the action view that appears in the 30bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * {@link android.app.ActionBar} as a substitute for the menu item when the item is 31bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * displayed as an action item. Also the provider is responsible for performing a 32bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * default action if a menu item placed on the overflow menu of the ActionBar is 33bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * selected and none of the menu item callbacks has handled the selection. For this 34bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * case the provider can also optionally provide a sub-menu for accomplishing the 35bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * task at hand. 36bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </p> 37bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <p> 38bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * There are two ways for using an action provider for creating and handling of action views: 39bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <ul> 40bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <li> 41bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Setting the action provider on a {@link MenuItem} directly by calling 42bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * {@link MenuItem#setActionProvider(ActionProvider)}. 43bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </li> 44bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <li> 45bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Declaring the action provider in the menu XML resource. For example: 46bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <pre> 47bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <code> 48bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <item android:id="@+id/my_menu_item" 49bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * android:title="Title" 50bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * android:icon="@drawable/my_menu_item_icon" 51bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * android:showAsAction="ifRoom" 52bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * android:actionProviderClass="foo.bar.SomeActionProvider" /> 53bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </code> 54bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </pre> 55bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </li> 56bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </ul> 57bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </p> 58bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 59bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @see MenuItem#setActionProvider(ActionProvider) 60bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @see MenuItem#getActionProvider() 61bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 62bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellpublic abstract class ActionProvider { 63bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell private SubUiVisibilityListener mSubUiVisibilityListener; 64bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 65bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 66bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Creates a new instance. 67bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 68bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @param context Context for accessing resources. 69bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 70bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public ActionProvider(Context context) { 71bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 72bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 73bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 74bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Factory method for creating new action views. 75bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 76bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @return A new action view. 77bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 78bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public abstract View onCreateActionView(); 79bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 80bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 81bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Performs an optional default action. 82bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <p> 83bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * For the case of an action provider placed in a menu item not shown as an action this 84bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * method is invoked if previous callbacks for processing menu selection has handled 85bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * the event. 86bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </p> 87bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <p> 88bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * A menu item selection is processed in the following order: 89bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <ul> 90bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <li> 91bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick 92bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * MenuItem.OnMenuItemClickListener.onMenuItemClick}. 93bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </li> 94bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <li> 95bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem) 96bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Activity.onOptionsItemSelected(MenuItem)} 97bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </li> 98bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <li> 99bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem) 100bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Fragment.onOptionsItemSelected(MenuItem)} 101bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </li> 102bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <li> 103bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Launching the {@link android.content.Intent} set via 104bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)} 105bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </li> 106bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <li> 107bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Invoking this method. 108bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </li> 109bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </ul> 110bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </p> 111bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <p> 112bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * The default implementation does not perform any action and returns false. 113bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * </p> 114bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 115bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public boolean onPerformDefaultAction() { 116bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell return false; 117bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 118bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 119bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 120bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Determines if this ActionProvider has a submenu associated with it. 121bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 122bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <p>Associated submenus will be shown when an action view is not. This 123bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)} 124bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * after the call to {@link #onPerformDefaultAction()} and before a submenu is 125bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * displayed to the user. 126bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 127bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @return true if the item backed by this provider should have an associated submenu 128bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 129bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public boolean hasSubMenu() { 130bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell return false; 131bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 132bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 133bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 134bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Called to prepare an associated submenu for the menu item backed by this ActionProvider. 135bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 136bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * <p>if {@link #hasSubMenu()} returns true, this method will be called when the 137bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * menu item is selected to prepare the submenu for presentation to the user. Apps 138bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * may use this to create or alter submenu content right before display. 139bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 140bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @param subMenu Submenu that will be displayed 141bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 142bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public void onPrepareSubMenu(SubMenu subMenu) { 143bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 144bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 145bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 146bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * Notify the system that the visibility of an action view's sub-UI such as 147bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * an anchored popup has changed. This will affect how other system 148bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * visibility notifications occur. 149bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 150bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @hide Pending future API approval 151bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 152bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public void subUiVisibilityChanged(boolean isVisible) { 153bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell if (mSubUiVisibilityListener != null) { 154bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible); 155bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 156bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 157bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 158bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 159bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @hide Internal use only 160bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 161bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public void setSubUiVisibilityListener(SubUiVisibilityListener listener) { 162bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell mSubUiVisibilityListener = listener; 163bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 164bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 165bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell /** 166bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * @hide Internal use only 167bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 168bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public interface SubUiVisibilityListener { 169bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell public void onSubUiVisibilityChanged(boolean isVisible); 170bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 171bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell} 172