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 { 61823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell private SubUiVisibilityListener mSubUiVisibilityListener; 6251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 6351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 6451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Creates a new instance. 6551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 6651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @param context Context for accessing resources. 6751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 6851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov public ActionProvider(Context context) { 6951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov } 7051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 7151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 7251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Factory method for creating new action views. 7351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 7451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * @return A new action view. 7551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 7651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov public abstract View onCreateActionView(); 7751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov 7851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov /** 7951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Performs an optional default action. 8051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 8151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * For the case of an action provider placed in a menu item not shown as an action this 82961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * method is invoked if previous callbacks for processing menu selection has handled 8351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * the event. 8451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 8551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 8651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * A menu item selection is processed in the following order: 8751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <ul> 8851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 8951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick 9051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * MenuItem.OnMenuItemClickListener.onMenuItemClick}. 9151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 9251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 9351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem) 9451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Activity.onOptionsItemSelected(MenuItem)} 9551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 9651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 9751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem) 9851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Fragment.onOptionsItemSelected(MenuItem)} 9951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 10051ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 10151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Launching the {@link android.content.Intent} set via 10251ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)} 10351ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 10451ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <li> 10551ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * Invoking this method. 10651ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </li> 10751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </ul> 10851ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 10951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * <p> 110961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * The default implementation does not perform any action and returns false. 11151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * </p> 112961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell */ 113961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public boolean onPerformDefaultAction() { 114961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell return false; 115961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell } 116961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell 117961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell /** 118961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * Determines if this ActionProvider has a submenu associated with it. 119961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 120961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * <p>Associated submenus will be shown when an action view is not. This 121961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)} 122961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * after the call to {@link #onPerformDefaultAction()} and before a submenu is 123961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * displayed to the user. 124961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 125961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * @return true if the item backed by this provider should have an associated submenu 126961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell */ 127961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public boolean hasSubMenu() { 128961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell return false; 129961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell } 130961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell 131961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell /** 132961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * Called to prepare an associated submenu for the menu item backed by this ActionProvider. 133961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * 134961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * <p>if {@link #hasSubMenu()} returns true, this method will be called when the 135961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * menu item is selected to prepare the submenu for presentation to the user. Apps 136961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * may use this to create or alter submenu content right before display. 13751ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov * 138961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell * @param subMenu Submenu that will be displayed 13951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov */ 140961dd11895ce72e59bca124ef5bea4e4c1183099Adam Powell public void onPrepareSubMenu(SubMenu subMenu) { 14151ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov } 142823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell 143823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell /** 144823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * Notify the system that the visibility of an action view's sub-UI such as 145823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * an anchored popup has changed. This will affect how other system 146823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * visibility notifications occur. 147823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * 148823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * @hide Pending future API approval 149823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell */ 150823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public void subUiVisibilityChanged(boolean isVisible) { 151823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell if (mSubUiVisibilityListener != null) { 152823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible); 153823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 154823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 155823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell 156823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell /** 157823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * @hide Internal use only 158823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell */ 159823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public void setSubUiVisibilityListener(SubUiVisibilityListener listener) { 160823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell mSubUiVisibilityListener = listener; 161823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 162823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell 163823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell /** 164823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell * @hide Internal use only 165823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell */ 166823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public interface SubUiVisibilityListener { 167823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell public void onSubUiVisibilityChanged(boolean isVisible); 168823f074a73cfc23c40a7b576c71daa096ee9ed6aAdam Powell } 16951ac0e94a83cfccb5105aa14df1077729a5b4cccSvetoslav Ganov} 170