ActionProvider.java revision 76559a65ad9d644f10beacf8895ceb217fdd0aeb
151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov/* 251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Copyright (C) 2011 The Android Open Source Project 351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Licensed under the Apache License, Version 2.0 (the "License"); 551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * you may not use this file except in compliance with the License. 651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * You may obtain a copy of the License at 751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * http://www.apache.org/licenses/LICENSE-2.0 951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 1051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Unless required by applicable law or agreed to in writing, software 1151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * distributed under the License is distributed on an "AS IS" BASIS, 1251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * See the License for the specific language governing permissions and 1451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * limitations under the License. 1551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 1651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 1751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganovpackage android.view; 1851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 1951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganovimport android.content.Context; 2051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 2151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov/** 2251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * This class is a mediator for accomplishing a given task, for example sharing a file. 2351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * It is responsible for creating a view that performs an action that accomplishes the task. 2451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * This class also implements other functions such a performing a default action. 2551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 2651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * An ActionProvider can be optionally specified for a {@link MenuItem} and in such a 2751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * case it will be responsible for creating the action view that appears in the 2851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * {@link android.app.ActionBar} as a substitute for the menu item when the item is 2951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * displayed as an action item. Also the provider is responsible for performing a 3051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * default action if a menu item placed on the overflow menu of the ActionBar is 3176559a65ad9d644f10beacf8895ceb217fdd0aebSvetoslav Ganov * selected and none of the menu item callbacks has handled the selection. For this 3276559a65ad9d644f10beacf8895ceb217fdd0aebSvetoslav Ganov * case the provider can also optionally provide a sub-menu for accomplishing the 3376559a65ad9d644f10beacf8895ceb217fdd0aebSvetoslav Ganov * task at hand. 3451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 3551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 3651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * There are two ways for using an action provider for creating and handling of action views: 3751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <ul> 3851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 3951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Setting the action provider on a {@link MenuItem} directly by calling 4051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * {@link MenuItem#setActionProvider(ActionProvider)}. 4151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 4251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 4351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Declaring the action provider in the menu XML resource. For example: 4451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <pre> 4551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <code> 4651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <item android:id="@+id/my_menu_item" 4751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:title="Title" 4851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:icon="@drawable/my_menu_item_icon" 4951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:showAsAction="ifRoom" 5051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:actionProviderClass="foo.bar.SomeActionProvider" /> 5151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </code> 5251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </pre> 5351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 5451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </ul> 5551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 5651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 5751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @see MenuItem#setActionProvider(ActionProvider) 5851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @see MenuItem#getActionProvider() 5951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 6051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganovpublic abstract class ActionProvider { 6151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 6251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 6351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Creates a new instance. 6451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 6551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @param context Context for accessing resources. 6651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 6751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov public ActionProvider(Context context) { 6851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov } 6951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 7051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 7151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Factory method for creating new action views. 7251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 7351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @return A new action view. 7451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 7551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov public abstract View onCreateActionView(); 7651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 7751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 7851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Performs an optional default action. 7951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 8051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * For the case of an action provider placed in a menu item not shown as an action this 81961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * method is invoked if previous callbacks for processing menu selection has handled 8251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * the event. 8351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 8451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 8551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * A menu item selection is processed in the following order: 8651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <ul> 8751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 8851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick 8951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * MenuItem.OnMenuItemClickListener.onMenuItemClick}. 9051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 9151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 9251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem) 9351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Activity.onOptionsItemSelected(MenuItem)} 9451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 9551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 9651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem) 9751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Fragment.onOptionsItemSelected(MenuItem)} 9851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 9951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 10051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Launching the {@link android.content.Intent} set via 10151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)} 10251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 10351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 10451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Invoking this method. 10551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 10651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </ul> 10751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 10851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 109961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * The default implementation does not perform any action and returns false. 11051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 111961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell */ 112961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public boolean onPerformDefaultAction() { 113961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell return false; 114961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell } 115961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell 116961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell /** 117961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * Determines if this ActionProvider has a submenu associated with it. 118961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 119961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * <p>Associated submenus will be shown when an action view is not. This 120961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)} 121961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * after the call to {@link #onPerformDefaultAction()} and before a submenu is 122961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * displayed to the user. 123961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 124961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * @return true if the item backed by this provider should have an associated submenu 125961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell */ 126961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public boolean hasSubMenu() { 127961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell return false; 128961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell } 129961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell 130961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell /** 131961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * Called to prepare an associated submenu for the menu item backed by this ActionProvider. 132961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 133961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * <p>if {@link #hasSubMenu()} returns true, this method will be called when the 134961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * menu item is selected to prepare the submenu for presentation to the user. Apps 135961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * may use this to create or alter submenu content right before display. 13651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 137961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * @param subMenu Submenu that will be displayed 13851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 139961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public void onPrepareSubMenu(SubMenu subMenu) { 14051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov } 14151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov} 142