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