ActionProvider.java revision 30837f1095c803f332f4a1c3f0917c8afdd50156
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 1730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellpackage android.support.v4.view; 18bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 19bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellimport android.content.Context; 2030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellimport android.view.SubMenu; 21bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellimport android.view.View; 22bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 23bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell/** 2420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * This class is a mediator for accomplishing a given task, for example sharing a file. It is 2520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * responsible for creating a view that performs an action that accomplishes the task. This class 2620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * also implements other functions such a performing a default action. 2720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 2820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <p>An ActionProvider can be 2930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * optionally specified for a {@link android.view.MenuItem} and in such a case it will be 30e0f27d39b0a4f0ef30ef6446e7b675279961cc94Chris Banes * responsible for 3120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * creating the action view that appears in the {@link android.app.ActionBar} as a substitute for 3220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * the menu item when the item is displayed as an action item. Also the provider is responsible for 3320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * performing a default action if a menu item placed on the overflow menu of the ActionBar is 3420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * selected and none of the menu item callbacks has handled the selection. For this case the 3520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * provider can also optionally provide a sub-menu for accomplishing the task at hand. 3620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 3720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <p>There are two ways for using an action provider for creating and handling of action views: 3820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 3930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * <ul><li> Setting the action provider on a {@link android.view.MenuItem} directly by 4030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * calling {@link 4130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * android.support.v4.view.MenuItemCompat#setActionProvider(android.view.MenuItem, ActionProvider)}. 4230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * </li> 4320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 4420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <li>Declaring the action provider in the menu XML resource. For example: 4520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 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> 5520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * </li></ul></p> 56bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell * 5730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see android.support.v4.view.MenuItemCompat#setActionProvider(android.view.MenuItem, ActionProvider) 5830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see android.support.v4.view.MenuItemCompat#getActionProvider(android.view.MenuItem) 59bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell */ 60bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powellpublic abstract class ActionProvider { 61e6072e2d918169bd827cf7431347fb648124c227Jeff Brown private final Context mContext; 62bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 6320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns private SubUiVisibilityListener mSubUiVisibilityListener; 64bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 6520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 6620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * Creates a new instance. 6720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 6820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * @param context Context for accessing resources. 6920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 7020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public ActionProvider(Context context) { 71e6072e2d918169bd827cf7431347fb648124c227Jeff Brown mContext = context; 72e6072e2d918169bd827cf7431347fb648124c227Jeff Brown } 73e6072e2d918169bd827cf7431347fb648124c227Jeff Brown 74e6072e2d918169bd827cf7431347fb648124c227Jeff Brown /** 75e6072e2d918169bd827cf7431347fb648124c227Jeff Brown * Gets the context associated with this action provider. 76e6072e2d918169bd827cf7431347fb648124c227Jeff Brown */ 77e6072e2d918169bd827cf7431347fb648124c227Jeff Brown public Context getContext() { 78e6072e2d918169bd827cf7431347fb648124c227Jeff Brown return mContext; 7920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns } 80bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 8120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 8220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * Factory method for creating new action views. 8320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 8420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * @return A new action view. 8520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 8620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public abstract View onCreateActionView(); 87bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 8820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 8920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * Performs an optional default action. 9020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 9120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <p>For the case of an action provider placed in a menu 9220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * item not shown as an action this method is invoked if previous callbacks for processing menu 9320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * selection has handled the event. 9420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 9520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <p> A menu item selection is processed in the following order: 9620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 97e0f27d39b0a4f0ef30ef6446e7b675279961cc94Chris Banes * <ul><li>Receiving a call to 9830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * {@link android.view.MenuItem.OnMenuItemClickListener#onMenuItemClick 9920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * MenuItem.OnMenuItemClickListener.onMenuItemClick}.</li> 10020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 101e0f27d39b0a4f0ef30ef6446e7b675279961cc94Chris Banes * <li>Receiving a call to 10230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * {@link android.app.Activity#onOptionsItemSelected(android.view.MenuItem)} 10330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * FragmentActivity.onOptionsItemSelected(MenuItem)} 10420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * </li> 10520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 106e0f27d39b0a4f0ef30ef6446e7b675279961cc94Chris Banes * <li>Receiving a call to 10730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * {@link android.support.v4.app.Fragment#onOptionsItemSelected(android.view.MenuItem)} 10830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Fragment.onOptionsItemSelected(MenuItem)}</li> 10920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 11020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <li>Launching the {@link android.content.Intent} set via 11130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * {@link android.view.MenuItem#setIntent(android.content.Intent) 112e0f27d39b0a4f0ef30ef6446e7b675279961cc94Chris Banes * MenuItem.setIntent(android.content.Intent)} 11320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * </li> 11420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 11520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <li>Invoking this method.</li></ul> 11620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 11720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <p>The default implementation does not perform any action and returns false. 11820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 11920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public boolean onPerformDefaultAction() { 12020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns return false; 12120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns } 122bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 12320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 12420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * Determines if this ActionProvider has a submenu associated with it. 12520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 12620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <p>Associated submenus will be shown when an action view is not. This provider instance will 12720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * receive a call to {@link #onPrepareSubMenu(SubMenu)} after the call to {@link 12820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * #onPerformDefaultAction()} and before a submenu is displayed to the user. 12920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 13020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * @return true if the item backed by this provider should have an associated submenu 13120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 13220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public boolean hasSubMenu() { 13320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns return false; 13420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns } 13520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns 13620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 13720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * Called to prepare an associated submenu for the menu item backed by this ActionProvider. 13820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 13920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * <p>if {@link #hasSubMenu()} returns true, this method will be called when the menu item is 14020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * selected to prepare the submenu for presentation to the user. Apps may use this to create or 14120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * alter submenu content right before display. 14220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 14320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * @param subMenu Submenu that will be displayed 14420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 14520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public void onPrepareSubMenu(SubMenu subMenu) { 14620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns } 147bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 14820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 14920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * Notify the system that the visibility of an action view's sub-UI such as an anchored popup 15020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * has changed. This will affect how other system visibility notifications occur. 15120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * 15220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * @hide Pending future API approval 15320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 15420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public void subUiVisibilityChanged(boolean isVisible) { 15520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns if (mSubUiVisibilityListener != null) { 15620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible); 15720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns } 158bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell } 159bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 16020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 16120ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * @hide Internal use only 16220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 16320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public void setSubUiVisibilityListener(SubUiVisibilityListener listener) { 16420ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns mSubUiVisibilityListener = listener; 16520ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns } 16620ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns 16720ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns /** 16820ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns * @hide Internal use only 16920ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns */ 17020ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public interface SubUiVisibilityListener { 171bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell 17220ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns public void onSubUiVisibilityChanged(boolean isVisible); 17320ac724a3a836bfd362c911f7dc55a61c02b4d44Trevor Johns } 174bbbb8f39d1b1d1b317c5f9237f20fe6b1d9eb17fAdam Powell} 175