ActionProvider.java revision 690ffb4e1f735148a15f2036d9a3c1962fba188c
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/** 229a1de308cea2d160778fd977825f10a07b49d738Adam Powell * An ActionProvider defines rich menu interaction in a single component. 239a1de308cea2d160778fd977825f10a07b49d738Adam Powell * ActionProvider can generate action views for use in the action bar, 249a1de308cea2d160778fd977825f10a07b49d738Adam Powell * dynamically populate submenus of a MenuItem, and handle default menu 259a1de308cea2d160778fd977825f10a07b49d738Adam Powell * item invocations. 269a1de308cea2d160778fd977825f10a07b49d738Adam Powell * 279a1de308cea2d160778fd977825f10a07b49d738Adam Powell * <p>An ActionProvider can be optionally specified for a {@link MenuItem} and will be 289a1de308cea2d160778fd977825f10a07b49d738Adam Powell * responsible for creating the action view that appears in the {@link android.app.ActionBar} 299a1de308cea2d160778fd977825f10a07b49d738Adam Powell * in place of a simple button in the bar. When the menu item is presented in a way that 309a1de308cea2d160778fd977825f10a07b49d738Adam Powell * does not allow custom action views, (e.g. in an overflow menu,) the ActionProvider 319a1de308cea2d160778fd977825f10a07b49d738Adam Powell * can perform a default action.</p> 329a1de308cea2d160778fd977825f10a07b49d738Adam Powell * 339a1de308cea2d160778fd977825f10a07b49d738Adam Powell * <p>There are two ways to use an action provider: 3451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <ul> 3551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 369a1de308cea2d160778fd977825f10a07b49d738Adam Powell * Set the action provider on a {@link MenuItem} directly by calling 3751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * {@link MenuItem#setActionProvider(ActionProvider)}. 3851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 3951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 409a1de308cea2d160778fd977825f10a07b49d738Adam Powell * Declare the action provider in an XML menu resource. For example: 4151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <pre> 4251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <code> 4351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <item android:id="@+id/my_menu_item" 4451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:title="Title" 4551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:icon="@drawable/my_menu_item_icon" 4651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:showAsAction="ifRoom" 4751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * android:actionProviderClass="foo.bar.SomeActionProvider" /> 4851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </code> 4951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </pre> 5051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 5151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </ul> 5251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 5351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 5451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @see MenuItem#setActionProvider(ActionProvider) 5551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @see MenuItem#getActionProvider() 5651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 5751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganovpublic abstract class ActionProvider { 58823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell private SubUiVisibilityListener mSubUiVisibilityListener; 5951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 6051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 61690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * Creates a new instance. ActionProvider classes should always implement a 62690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * constructor that takes a single Context parameter for inflating from menu XML. 6351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 6451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @param context Context for accessing resources. 6551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 6651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov public ActionProvider(Context context) { 6751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov } 6851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 6951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 70690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * Factory method called by the Android framework to create new action views. 71690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * 72690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * <p>This method has been deprecated in favor of {@link #onCreateActionView(MenuItem)}. 73690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * Newer apps that wish to support platform versions prior to API 16 should also 74690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * implement this method to return a valid action view.</p> 7551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 7651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @return A new action view. 77690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * 78690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * @deprecated use {@link #onCreateActionView(MenuItem)} 7951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 8051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov public abstract View onCreateActionView(); 8151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 8251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 83690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * Factory method called by the Android framework to create new action views. 84690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * This method returns a new action view for the given MenuItem. 85690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * 86690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * <p>If your ActionProvider implementation overrides the deprecated no-argument overload 87690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * {@link #onCreateActionView()}, overriding this method for devices running API 16 or later 88690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * is recommended but optional. The default implementation calls {@link #onCreateActionView()} 89690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * for compatibility with applications written for older platform versions.</p> 90690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * 91690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * @param forItem MenuItem to create the action view for 92690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell * @return the new action view 93690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell */ 94690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell public View onCreateActionView(MenuItem forItem) { 95690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell return onCreateActionView(); 96690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell } 97690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell 98690ffb4e1f735148a15f2036d9a3c1962fba188cAdam Powell /** 9951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Performs an optional default action. 10051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 10151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * For the case of an action provider placed in a menu item not shown as an action this 102961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * method is invoked if previous callbacks for processing menu selection has handled 10351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * the event. 10451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 10551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 10651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * A menu item selection is processed in the following order: 10751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <ul> 10851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 10951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick 11051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * MenuItem.OnMenuItemClickListener.onMenuItemClick}. 11151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 11251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 11351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem) 11451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Activity.onOptionsItemSelected(MenuItem)} 11551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 11651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 11751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem) 11851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Fragment.onOptionsItemSelected(MenuItem)} 11951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 12051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 12151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Launching the {@link android.content.Intent} set via 12251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)} 12351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 12451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 12551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Invoking this method. 12651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 12751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </ul> 12851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 12951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 130961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * The default implementation does not perform any action and returns false. 13151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 132961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell */ 133961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public boolean onPerformDefaultAction() { 134961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell return false; 135961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell } 136961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell 137961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell /** 138961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * Determines if this ActionProvider has a submenu associated with it. 139961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 140961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * <p>Associated submenus will be shown when an action view is not. This 141961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)} 142961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * after the call to {@link #onPerformDefaultAction()} and before a submenu is 143961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * displayed to the user. 144961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 145961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * @return true if the item backed by this provider should have an associated submenu 146961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell */ 147961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public boolean hasSubMenu() { 148961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell return false; 149961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell } 150961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell 151961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell /** 152961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * Called to prepare an associated submenu for the menu item backed by this ActionProvider. 153961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 154961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * <p>if {@link #hasSubMenu()} returns true, this method will be called when the 155961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * menu item is selected to prepare the submenu for presentation to the user. Apps 156961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * may use this to create or alter submenu content right before display. 15751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 158961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * @param subMenu Submenu that will be displayed 15951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 160961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public void onPrepareSubMenu(SubMenu subMenu) { 16151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov } 162823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell 163823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell /** 164823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * Notify the system that the visibility of an action view's sub-UI such as 165823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * an anchored popup has changed. This will affect how other system 166823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * visibility notifications occur. 167823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * 168823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * @hide Pending future API approval 169823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell */ 170823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public void subUiVisibilityChanged(boolean isVisible) { 171823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell if (mSubUiVisibilityListener != null) { 172823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible); 173823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 174823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 175823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell 176823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell /** 177823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * @hide Internal use only 178823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell */ 179823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public void setSubUiVisibilityListener(SubUiVisibilityListener listener) { 180823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell mSubUiVisibilityListener = listener; 181823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 182823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell 183823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell /** 184823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * @hide Internal use only 185823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell */ 186823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public interface SubUiVisibilityListener { 187823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public void onSubUiVisibilityChanged(boolean isVisible); 188823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 18951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov} 190