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