1 /* 2 * Copyright (C) 2013 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 17 package android.support.v4.internal.view; 18 19 import android.support.v4.view.ActionProvider; 20 import android.support.v4.view.MenuItemCompat; 21 import android.view.MenuItem; 22 import android.view.View; 23 24 /** 25 * Interface for direct access to a previously created menu item. 26 * 27 * This version extends the one available in the framework to ensures that any necessary 28 * elements added in later versions of the framework, are available for all platforms. 29 * 30 * @see android.view.MenuItem 31 * @hide 32 */ 33 public interface SupportMenuItem extends android.view.MenuItem { 34 /* 35 * These should be kept in sync with attrs.xml enum constants for showAsAction 36 */ 37 /** 38 * Never show this item as a button in an Action Bar. 39 */ 40 public static final int SHOW_AS_ACTION_NEVER = 0; 41 /** 42 * Show this item as a button in an Action Bar if the system decides there is room for it. 43 */ 44 public static final int SHOW_AS_ACTION_IF_ROOM = 1; 45 /** 46 * Always show this item as a button in an Action Bar. 47 * Use sparingly! If too many items are set to always show in the Action Bar it can 48 * crowd the Action Bar and degrade the user experience on devices with smaller screens. 49 * A good rule of thumb is to have no more than 2 items set to always show at a time. 50 */ 51 public static final int SHOW_AS_ACTION_ALWAYS = 2; 52 53 /** 54 * When this item is in the action bar, always show it with a text label even if it also has an 55 * icon specified. 56 */ 57 public static final int SHOW_AS_ACTION_WITH_TEXT = 4; 58 59 /** 60 * This item's action view collapses to a normal menu item. When expanded, the action view 61 * temporarily takes over a larger segment of its container. 62 */ 63 public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8; 64 65 /** 66 * Sets how this item should display in the presence of an Action Bar. The parameter actionEnum 67 * is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or 68 * {@link #SHOW_AS_ACTION_NEVER} should be used, and you may optionally OR the value with {@link 69 * #SHOW_AS_ACTION_WITH_TEXT}. SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as 70 * an action, it should be shown with a text label. 71 * 72 * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link 73 * #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}. 74 * SHOW_AS_ACTION_NEVER is the default. 75 * @see android.app.ActionBar 76 * @see #setActionView(View) 77 */ setShowAsAction(int actionEnum)78 public void setShowAsAction(int actionEnum); 79 80 /** 81 * Sets how this item should display in the presence of an Action Bar. 82 * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, 83 * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should 84 * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. 85 * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, 86 * it should be shown with a text label. 87 * 88 * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it 89 * returns the current MenuItem instance for call chaining. 90 * 91 * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link 92 * #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}. 93 * SHOW_AS_ACTION_NEVER is the default. 94 * @return This MenuItem instance for call chaining. 95 * @see android.app.ActionBar 96 * @see #setActionView(View) 97 */ setShowAsActionFlags(int actionEnum)98 public MenuItem setShowAsActionFlags(int actionEnum); 99 100 /** 101 * Set an action view for this menu item. An action view will be displayed in place 102 * of an automatically generated menu item element in the UI when this item is shown 103 * as an action within a parent. 104 * 105 * <p><strong>Note:</strong> Setting an action view overrides the action provider 106 * provider set via {@link #setSupportActionProvider(android.support.v4.view.ActionProvider)}. </p> 107 * 108 * @param view View to use for presenting this item to the user. 109 * @return This Item so additional setters can be called. 110 * @see #setShowAsAction(int) 111 */ setActionView(View view)112 public MenuItem setActionView(View view); 113 114 /** 115 * Set an action view for this menu item. An action view will be displayed in place 116 * of an automatically generated menu item element in the UI when this item is shown 117 * as an action within a parent. 118 * 119 * <p><strong>Note:</strong> Setting an action view overrides the action provider 120 * provider set via {@link #setSupportActionProvider(android.support.v4.view.ActionProvider)}. </p> 121 * 122 * @param resId Layout resource to use for presenting this item to the user. 123 * @return This Item so additional setters can be called. 124 * @see #setShowAsAction(int) 125 */ setActionView(int resId)126 public MenuItem setActionView(int resId); 127 128 /** 129 * Returns the currently set action view for this menu item. 130 * 131 * @return This item's action view 132 * @see #setActionView(View) 133 * @see #setShowAsAction(int) 134 */ getActionView()135 public View getActionView(); 136 137 /** 138 * Sets the {@link android.support.v4.view.ActionProvider} responsible for creating an action view if 139 * the item is placed on the action bar. The provider also provides a default 140 * action invoked if the item is placed in the overflow menu. 141 * 142 * <p><strong>Note:</strong> Setting an action provider overrides the action view 143 * set via {@link #setActionView(int)} or {@link #setActionView(View)}. 144 * </p> 145 * 146 * @param actionProvider The action provider. 147 * @return This Item so additional setters can be called. 148 * @see android.support.v4.view.ActionProvider 149 */ setSupportActionProvider(ActionProvider actionProvider)150 public SupportMenuItem setSupportActionProvider(ActionProvider actionProvider); 151 152 /** 153 * Gets the {@link ActionProvider}. 154 * 155 * @return The action provider. 156 * @see ActionProvider 157 * @see #setSupportActionProvider(ActionProvider) 158 */ getSupportActionProvider()159 public ActionProvider getSupportActionProvider(); 160 161 /** 162 * Expand the action view associated with this menu item. The menu item must have an action view 163 * set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a 164 * listener has been set using {@link #setSupportOnActionExpandListener(android.support.v4.view.MenuItemCompat.OnActionExpandListener)} 165 * it will have its {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener#onMenuItemActionExpand(MenuItem)} method 166 * invoked. The listener may return false from this method to prevent expanding the action view. 167 * 168 * @return true if the action view was expanded, false otherwise. 169 */ expandActionView()170 public boolean expandActionView(); 171 172 /** 173 * Collapse the action view associated with this menu item. The menu item must have an action 174 * view set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a 175 * listener has been set using {@link #setSupportOnActionExpandListener(android.support.v4.view.MenuItemCompat.OnActionExpandListener)} 176 * it will have its {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener#onMenuItemActionCollapse(MenuItem)} method 177 * invoked. The listener may return false from this method to prevent collapsing the action 178 * view. 179 * 180 * @return true if the action view was collapsed, false otherwise. 181 */ collapseActionView()182 public boolean collapseActionView(); 183 184 /** 185 * Returns true if this menu item's action view has been expanded. 186 * 187 * @return true if the item's action view is expanded, false otherwise. 188 * @see #expandActionView() 189 * @see #collapseActionView() 190 * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW 191 * @see android.support.v4.view.MenuItemCompat.OnActionExpandListener 192 */ isActionViewExpanded()193 public boolean isActionViewExpanded(); 194 195 /** 196 * Set an {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener} on this menu item to be notified when the associated 197 * action view is expanded or collapsed. The menu item must be configured to expand or collapse 198 * its action view using the flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. 199 * 200 * @param listener Listener that will respond to expand/collapse events 201 * @return This menu item instance for call chaining 202 */ setSupportOnActionExpandListener(MenuItemCompat.OnActionExpandListener listener)203 public SupportMenuItem setSupportOnActionExpandListener(MenuItemCompat.OnActionExpandListener listener); 204 }