1 /* 2 * Copyright (C) 2008 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.view; 18 19 import android.annotation.DrawableRes; 20 import android.annotation.LayoutRes; 21 import android.annotation.Nullable; 22 import android.annotation.StringRes; 23 import android.app.Activity; 24 import android.content.Intent; 25 import android.content.res.ColorStateList; 26 import android.graphics.PorterDuff; 27 import android.graphics.drawable.Drawable; 28 import android.view.ContextMenu.ContextMenuInfo; 29 import android.view.View.OnCreateContextMenuListener; 30 31 /** 32 * Interface for direct access to a previously created menu item. 33 * <p> 34 * An Item is returned by calling one of the {@link android.view.Menu#add} 35 * methods. 36 * <p> 37 * For a feature set of specific menu types, see {@link Menu}. 38 * 39 * <div class="special reference"> 40 * <h3>Developer Guides</h3> 41 * <p>For information about creating menus, read the 42 * <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide.</p> 43 * </div> 44 */ 45 public interface MenuItem { 46 /* 47 * These should be kept in sync with attrs.xml enum constants for showAsAction 48 */ 49 /** Never show this item as a button in an Action Bar. */ 50 public static final int SHOW_AS_ACTION_NEVER = 0; 51 /** Show this item as a button in an Action Bar if the system decides there is room for it. */ 52 public static final int SHOW_AS_ACTION_IF_ROOM = 1; 53 /** 54 * Always show this item as a button in an Action Bar. 55 * Use sparingly! If too many items are set to always show in the Action Bar it can 56 * crowd the Action Bar and degrade the user experience on devices with smaller screens. 57 * A good rule of thumb is to have no more than 2 items set to always show at a time. 58 */ 59 public static final int SHOW_AS_ACTION_ALWAYS = 2; 60 61 /** 62 * When this item is in the action bar, always show it with a text label even if 63 * it also has an icon specified. 64 */ 65 public static final int SHOW_AS_ACTION_WITH_TEXT = 4; 66 67 /** 68 * This item's action view collapses to a normal menu item. 69 * When expanded, the action view temporarily takes over 70 * a larger segment of its container. 71 */ 72 public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8; 73 74 /** 75 * Interface definition for a callback to be invoked when a menu item is 76 * clicked. 77 * 78 * @see Activity#onContextItemSelected(MenuItem) 79 * @see Activity#onOptionsItemSelected(MenuItem) 80 */ 81 public interface OnMenuItemClickListener { 82 /** 83 * Called when a menu item has been invoked. This is the first code 84 * that is executed; if it returns true, no other callbacks will be 85 * executed. 86 * 87 * @param item The menu item that was invoked. 88 * 89 * @return Return true to consume this click and prevent others from 90 * executing. 91 */ onMenuItemClick(MenuItem item)92 public boolean onMenuItemClick(MenuItem item); 93 } 94 95 /** 96 * Interface definition for a callback to be invoked when a menu item 97 * marked with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} is 98 * expanded or collapsed. 99 * 100 * @see MenuItem#expandActionView() 101 * @see MenuItem#collapseActionView() 102 * @see MenuItem#setShowAsActionFlags(int) 103 */ 104 public interface OnActionExpandListener { 105 /** 106 * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} 107 * is expanded. 108 * @param item Item that was expanded 109 * @return true if the item should expand, false if expansion should be suppressed. 110 */ onMenuItemActionExpand(MenuItem item)111 public boolean onMenuItemActionExpand(MenuItem item); 112 113 /** 114 * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} 115 * is collapsed. 116 * @param item Item that was collapsed 117 * @return true if the item should collapse, false if collapsing should be suppressed. 118 */ onMenuItemActionCollapse(MenuItem item)119 public boolean onMenuItemActionCollapse(MenuItem item); 120 } 121 122 /** 123 * Return the identifier for this menu item. The identifier can not 124 * be changed after the menu is created. 125 * 126 * @return The menu item's identifier. 127 */ getItemId()128 public int getItemId(); 129 130 /** 131 * Return the group identifier that this menu item is part of. The group 132 * identifier can not be changed after the menu is created. 133 * 134 * @return The menu item's group identifier. 135 */ getGroupId()136 public int getGroupId(); 137 138 /** 139 * Return the category and order within the category of this item. This 140 * item will be shown before all items (within its category) that have 141 * order greater than this value. 142 * <p> 143 * An order integer contains the item's category (the upper bits of the 144 * integer; set by or/add the category with the order within the 145 * category) and the ordering of the item within that category (the 146 * lower bits). Example categories are {@link Menu#CATEGORY_SYSTEM}, 147 * {@link Menu#CATEGORY_SECONDARY}, {@link Menu#CATEGORY_ALTERNATIVE}, 148 * {@link Menu#CATEGORY_CONTAINER}. See {@link Menu} for a full list. 149 * 150 * @return The order of this item. 151 */ getOrder()152 public int getOrder(); 153 154 /** 155 * Change the title associated with this item. 156 * 157 * @param title The new text to be displayed. 158 * @return This Item so additional setters can be called. 159 */ setTitle(CharSequence title)160 public MenuItem setTitle(CharSequence title); 161 162 /** 163 * Change the title associated with this item. 164 * <p> 165 * Some menu types do not sufficient space to show the full title, and 166 * instead a condensed title is preferred. See {@link Menu} for more 167 * information. 168 * 169 * @param title The resource id of the new text to be displayed. 170 * @return This Item so additional setters can be called. 171 * @see #setTitleCondensed(CharSequence) 172 */ 173 setTitle(@tringRes int title)174 public MenuItem setTitle(@StringRes int title); 175 176 /** 177 * Retrieve the current title of the item. 178 * 179 * @return The title. 180 */ getTitle()181 public CharSequence getTitle(); 182 183 /** 184 * Change the condensed title associated with this item. The condensed 185 * title is used in situations where the normal title may be too long to 186 * be displayed. 187 * 188 * @param title The new text to be displayed as the condensed title. 189 * @return This Item so additional setters can be called. 190 */ setTitleCondensed(CharSequence title)191 public MenuItem setTitleCondensed(CharSequence title); 192 193 /** 194 * Retrieve the current condensed title of the item. If a condensed 195 * title was never set, it will return the normal title. 196 * 197 * @return The condensed title, if it exists. 198 * Otherwise the normal title. 199 */ getTitleCondensed()200 public CharSequence getTitleCondensed(); 201 202 /** 203 * Change the icon associated with this item. This icon will not always be 204 * shown, so the title should be sufficient in describing this item. See 205 * {@link Menu} for the menu types that support icons. 206 * 207 * @param icon The new icon (as a Drawable) to be displayed. 208 * @return This Item so additional setters can be called. 209 */ setIcon(Drawable icon)210 public MenuItem setIcon(Drawable icon); 211 212 /** 213 * Change the icon associated with this item. This icon will not always be 214 * shown, so the title should be sufficient in describing this item. See 215 * {@link Menu} for the menu types that support icons. 216 * <p> 217 * This method will set the resource ID of the icon which will be used to 218 * lazily get the Drawable when this item is being shown. 219 * 220 * @param iconRes The new icon (as a resource ID) to be displayed. 221 * @return This Item so additional setters can be called. 222 */ setIcon(@rawableRes int iconRes)223 public MenuItem setIcon(@DrawableRes int iconRes); 224 225 /** 226 * Returns the icon for this item as a Drawable (getting it from resources if it hasn't been 227 * loaded before). Note that if you call {@link #setIconTintList(ColorStateList)} or 228 * {@link #setIconTintMode(PorterDuff.Mode)} on this item, and you use a custom menu presenter 229 * in your application, you have to apply the tinting explicitly on the {@link Drawable} 230 * returned by this method. 231 * 232 * @return The icon as a Drawable. 233 */ getIcon()234 public Drawable getIcon(); 235 236 /** 237 * Applies a tint to this item's icon. Does not modify the 238 * current tint mode, which is {@link PorterDuff.Mode#SRC_IN} by default. 239 * <p> 240 * Subsequent calls to {@link #setIcon(Drawable)} or {@link #setIcon(int)} will 241 * automatically mutate the icon and apply the specified tint and 242 * tint mode using 243 * {@link Drawable#setTintList(ColorStateList)}. 244 * 245 * @param tint the tint to apply, may be {@code null} to clear tint 246 * 247 * @attr ref android.R.styleable#MenuItem_iconTint 248 * @see #getIconTintList() 249 * @see Drawable#setTintList(ColorStateList) 250 */ setIconTintList(@ullable ColorStateList tint)251 public default MenuItem setIconTintList(@Nullable ColorStateList tint) { return this; } 252 253 /** 254 * @return the tint applied to this item's icon 255 * @attr ref android.R.styleable#MenuItem_iconTint 256 * @see #setIconTintList(ColorStateList) 257 */ 258 @Nullable getIconTintList()259 public default ColorStateList getIconTintList() { return null; } 260 261 /** 262 * Specifies the blending mode used to apply the tint specified by 263 * {@link #setIconTintList(ColorStateList)} to this item's icon. The default mode is 264 * {@link PorterDuff.Mode#SRC_IN}. 265 * 266 * @param tintMode the blending mode used to apply the tint, may be 267 * {@code null} to clear tint 268 * @attr ref android.R.styleable#MenuItem_iconTintMode 269 * @see #setIconTintList(ColorStateList) 270 * @see Drawable#setTintMode(PorterDuff.Mode) 271 */ setIconTintMode(@ullable PorterDuff.Mode tintMode)272 public default MenuItem setIconTintMode(@Nullable PorterDuff.Mode tintMode) { return this; } 273 274 /** 275 * Returns the blending mode used to apply the tint to this item's icon, if specified. 276 * 277 * @return the blending mode used to apply the tint to this item's icon 278 * @attr ref android.R.styleable#MenuItem_iconTintMode 279 * @see #setIconTintMode(PorterDuff.Mode) 280 */ 281 @Nullable getIconTintMode()282 public default PorterDuff.Mode getIconTintMode() { return null; } 283 284 /** 285 * Change the Intent associated with this item. By default there is no 286 * Intent associated with a menu item. If you set one, and nothing 287 * else handles the item, then the default behavior will be to call 288 * {@link android.content.Context#startActivity} with the given Intent. 289 * 290 * <p>Note that setIntent() can not be used with the versions of 291 * {@link Menu#add} that take a Runnable, because {@link Runnable#run} 292 * does not return a value so there is no way to tell if it handled the 293 * item. In this case it is assumed that the Runnable always handles 294 * the item, and the intent will never be started. 295 * 296 * @see #getIntent 297 * @param intent The Intent to associated with the item. This Intent 298 * object is <em>not</em> copied, so be careful not to 299 * modify it later. 300 * @return This Item so additional setters can be called. 301 */ setIntent(Intent intent)302 public MenuItem setIntent(Intent intent); 303 304 /** 305 * Return the Intent associated with this item. This returns a 306 * reference to the Intent which you can change as desired to modify 307 * what the Item is holding. 308 * 309 * @see #setIntent 310 * @return Returns the last value supplied to {@link #setIntent}, or 311 * null. 312 */ getIntent()313 public Intent getIntent(); 314 315 /** 316 * Change both the numeric and alphabetic shortcut associated with this 317 * item. Note that the shortcut will be triggered when the key that 318 * generates the given character is pressed along with the corresponding 319 * modifier key. The default modifier is {@link KeyEvent#META_CTRL_ON} in 320 * case nothing is specified. Also note that case is not significant and 321 * that alphabetic shortcut characters will be handled in lower case. 322 * <p> 323 * See {@link Menu} for the menu types that support shortcuts. 324 * 325 * @param numericChar The numeric shortcut key. This is the shortcut when 326 * using a numeric (e.g., 12-key) keyboard. 327 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 328 * using a keyboard with alphabetic keys. 329 * @return This Item so additional setters can be called. 330 */ setShortcut(char numericChar, char alphaChar)331 public MenuItem setShortcut(char numericChar, char alphaChar); 332 333 /** 334 * Change both the numeric and alphabetic shortcut associated with this 335 * item. Note that the shortcut will be triggered when the key that 336 * generates the given character is pressed along with the corresponding 337 * modifier key. Also note that case is not significant and that alphabetic 338 * shortcut characters will be handled in lower case. 339 * <p> 340 * See {@link Menu} for the menu types that support shortcuts. 341 * 342 * @param numericChar The numeric shortcut key. This is the shortcut when 343 * using a numeric (e.g., 12-key) keyboard. 344 * @param numericModifiers The numeric modifier associated with the shortcut. It should 345 * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, 346 * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, 347 * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. 348 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 349 * using a keyboard with alphabetic keys. 350 * @param alphaModifiers The alphabetic modifier associated with the shortcut. It should 351 * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, 352 * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, 353 * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. 354 * @return This Item so additional setters can be called. 355 */ setShortcut(char numericChar, char alphaChar, int numericModifiers, int alphaModifiers)356 default public MenuItem setShortcut(char numericChar, char alphaChar, int numericModifiers, 357 int alphaModifiers) { 358 if ((alphaModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON 359 && (numericModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON) { 360 return setShortcut(numericChar, alphaChar); 361 } else { 362 return this; 363 } 364 } 365 366 /** 367 * Change the numeric shortcut associated with this item. 368 * <p> 369 * See {@link Menu} for the menu types that support shortcuts. 370 * 371 * @param numericChar The numeric shortcut key. This is the shortcut when 372 * using a 12-key (numeric) keyboard. 373 * @return This Item so additional setters can be called. 374 */ setNumericShortcut(char numericChar)375 public MenuItem setNumericShortcut(char numericChar); 376 377 /** 378 * Change the numeric shortcut and modifiers associated with this item. 379 * <p> 380 * See {@link Menu} for the menu types that support shortcuts. 381 * 382 * @param numericChar The numeric shortcut key. This is the shortcut when 383 * using a 12-key (numeric) keyboard. 384 * @param numericModifiers The modifier associated with the shortcut. It should 385 * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, 386 * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, 387 * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. 388 * @return This Item so additional setters can be called. 389 */ setNumericShortcut(char numericChar, int numericModifiers)390 default public MenuItem setNumericShortcut(char numericChar, int numericModifiers) { 391 if ((numericModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON) { 392 return setNumericShortcut(numericChar); 393 } else { 394 return this; 395 } 396 } 397 398 /** 399 * Return the char for this menu item's numeric (12-key) shortcut. 400 * 401 * @return Numeric character to use as a shortcut. 402 */ getNumericShortcut()403 public char getNumericShortcut(); 404 405 /** 406 * Return the modifiers for this menu item's numeric (12-key) shortcut. 407 * The modifier is a combination of {@link KeyEvent#META_META_ON}, 408 * {@link KeyEvent#META_CTRL_ON}, {@link KeyEvent#META_ALT_ON}, 409 * {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_SYM_ON}, 410 * {@link KeyEvent#META_FUNCTION_ON}. 411 * For example, {@link KeyEvent#META_FUNCTION_ON}|{@link KeyEvent#META_CTRL_ON} 412 * 413 * @return Modifier associated with the numeric shortcut. 414 */ getNumericModifiers()415 default public int getNumericModifiers() { 416 return KeyEvent.META_CTRL_ON; 417 } 418 419 /** 420 * Change the alphabetic shortcut associated with this item. The shortcut 421 * will be triggered when the key that generates the given character is 422 * pressed along with the corresponding modifier key. The default modifier 423 * is {@link KeyEvent#META_CTRL_ON} in case nothing is specified. Case is 424 * not significant and shortcut characters will be displayed in lower case. 425 * Note that menu items with the characters '\b' or '\n' as shortcuts will 426 * get triggered by the Delete key or Carriage Return key, respectively. 427 * <p> 428 * See {@link Menu} for the menu types that support shortcuts. 429 * 430 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 431 * using a keyboard with alphabetic keys. 432 * @return This Item so additional setters can be called. 433 */ setAlphabeticShortcut(char alphaChar)434 public MenuItem setAlphabeticShortcut(char alphaChar); 435 436 /** 437 * Change the alphabetic shortcut associated with this item. The shortcut 438 * will be triggered when the key that generates the given character is 439 * pressed along with the modifier keys. Case is not significant and shortcut 440 * characters will be displayed in lower case. Note that menu items with 441 * the characters '\b' or '\n' as shortcuts will get triggered by the 442 * Delete key or Carriage Return key, respectively. 443 * <p> 444 * See {@link Menu} for the menu types that support shortcuts. 445 * 446 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 447 * using a keyboard with alphabetic keys. 448 * @param alphaModifiers The modifier associated with the shortcut. It should 449 * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, 450 * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, 451 * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. 452 * @return This Item so additional setters can be called. 453 */ setAlphabeticShortcut(char alphaChar, int alphaModifiers)454 default public MenuItem setAlphabeticShortcut(char alphaChar, int alphaModifiers) { 455 if ((alphaModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON) { 456 return setAlphabeticShortcut(alphaChar); 457 } else { 458 return this; 459 } 460 } 461 462 /** 463 * Return the char for this menu item's alphabetic shortcut. 464 * 465 * @return Alphabetic character to use as a shortcut. 466 */ getAlphabeticShortcut()467 public char getAlphabeticShortcut(); 468 469 /** 470 * Return the modifier for this menu item's alphabetic shortcut. 471 * The modifier is a combination of {@link KeyEvent#META_META_ON}, 472 * {@link KeyEvent#META_CTRL_ON}, {@link KeyEvent#META_ALT_ON}, 473 * {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_SYM_ON}, 474 * {@link KeyEvent#META_FUNCTION_ON}. 475 * For example, {@link KeyEvent#META_FUNCTION_ON}|{@link KeyEvent#META_CTRL_ON} 476 * 477 * @return Modifier associated with the keyboard shortcut. 478 */ getAlphabeticModifiers()479 default public int getAlphabeticModifiers() { 480 return KeyEvent.META_CTRL_ON; 481 } 482 483 /** 484 * Control whether this item can display a check mark. Setting this does 485 * not actually display a check mark (see {@link #setChecked} for that); 486 * rather, it ensures there is room in the item in which to display a 487 * check mark. 488 * <p> 489 * See {@link Menu} for the menu types that support check marks. 490 * 491 * @param checkable Set to true to allow a check mark, false to 492 * disallow. The default is false. 493 * @see #setChecked 494 * @see #isCheckable 495 * @see Menu#setGroupCheckable 496 * @return This Item so additional setters can be called. 497 */ setCheckable(boolean checkable)498 public MenuItem setCheckable(boolean checkable); 499 500 /** 501 * Return whether the item can currently display a check mark. 502 * 503 * @return If a check mark can be displayed, returns true. 504 * 505 * @see #setCheckable 506 */ isCheckable()507 public boolean isCheckable(); 508 509 /** 510 * Control whether this item is shown with a check mark. Note that you 511 * must first have enabled checking with {@link #setCheckable} or else 512 * the check mark will not appear. If this item is a member of a group that contains 513 * mutually-exclusive items (set via {@link Menu#setGroupCheckable(int, boolean, boolean)}, 514 * the other items in the group will be unchecked. 515 * <p> 516 * See {@link Menu} for the menu types that support check marks. 517 * 518 * @see #setCheckable 519 * @see #isChecked 520 * @see Menu#setGroupCheckable 521 * @param checked Set to true to display a check mark, false to hide 522 * it. The default value is false. 523 * @return This Item so additional setters can be called. 524 */ setChecked(boolean checked)525 public MenuItem setChecked(boolean checked); 526 527 /** 528 * Return whether the item is currently displaying a check mark. 529 * 530 * @return If a check mark is displayed, returns true. 531 * 532 * @see #setChecked 533 */ isChecked()534 public boolean isChecked(); 535 536 /** 537 * Sets the visibility of the menu item. Even if a menu item is not visible, 538 * it may still be invoked via its shortcut (to completely disable an item, 539 * set it to invisible and {@link #setEnabled(boolean) disabled}). 540 * 541 * @param visible If true then the item will be visible; if false it is 542 * hidden. 543 * @return This Item so additional setters can be called. 544 */ setVisible(boolean visible)545 public MenuItem setVisible(boolean visible); 546 547 /** 548 * Return the visibility of the menu item. 549 * 550 * @return If true the item is visible; else it is hidden. 551 */ isVisible()552 public boolean isVisible(); 553 554 /** 555 * Sets whether the menu item is enabled. Disabling a menu item will not 556 * allow it to be invoked via its shortcut. The menu item will still be 557 * visible. 558 * 559 * @param enabled If true then the item will be invokable; if false it is 560 * won't be invokable. 561 * @return This Item so additional setters can be called. 562 */ setEnabled(boolean enabled)563 public MenuItem setEnabled(boolean enabled); 564 565 /** 566 * Return the enabled state of the menu item. 567 * 568 * @return If true the item is enabled and hence invokable; else it is not. 569 */ isEnabled()570 public boolean isEnabled(); 571 572 /** 573 * Check whether this item has an associated sub-menu. I.e. it is a 574 * sub-menu of another menu. 575 * 576 * @return If true this item has a menu; else it is a 577 * normal item. 578 */ hasSubMenu()579 public boolean hasSubMenu(); 580 581 /** 582 * Get the sub-menu to be invoked when this item is selected, if it has 583 * one. See {@link #hasSubMenu()}. 584 * 585 * @return The associated menu if there is one, else null 586 */ getSubMenu()587 public SubMenu getSubMenu(); 588 589 /** 590 * Set a custom listener for invocation of this menu item. In most 591 * situations, it is more efficient and easier to use 592 * {@link Activity#onOptionsItemSelected(MenuItem)} or 593 * {@link Activity#onContextItemSelected(MenuItem)}. 594 * 595 * @param menuItemClickListener The object to receive invokations. 596 * @return This Item so additional setters can be called. 597 * @see Activity#onOptionsItemSelected(MenuItem) 598 * @see Activity#onContextItemSelected(MenuItem) 599 */ setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener)600 public MenuItem setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener); 601 602 /** 603 * Gets the extra information linked to this menu item. This extra 604 * information is set by the View that added this menu item to the 605 * menu. 606 * 607 * @see OnCreateContextMenuListener 608 * @return The extra information linked to the View that added this 609 * menu item to the menu. This can be null. 610 */ getMenuInfo()611 public ContextMenuInfo getMenuInfo(); 612 613 /** 614 * Sets how this item should display in the presence of an Action Bar. 615 * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, 616 * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should 617 * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. 618 * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, 619 * it should be shown with a text label. 620 * 621 * @param actionEnum How the item should display. One of 622 * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or 623 * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default. 624 * 625 * @see android.app.ActionBar 626 * @see #setActionView(View) 627 */ setShowAsAction(int actionEnum)628 public void setShowAsAction(int actionEnum); 629 630 /** 631 * Sets how this item should display in the presence of an Action Bar. 632 * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, 633 * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should 634 * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. 635 * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, 636 * it should be shown with a text label. 637 * 638 * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it 639 * returns the current MenuItem instance for call chaining. 640 * 641 * @param actionEnum How the item should display. One of 642 * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or 643 * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default. 644 * 645 * @see android.app.ActionBar 646 * @see #setActionView(View) 647 * @return This MenuItem instance for call chaining. 648 */ setShowAsActionFlags(int actionEnum)649 public MenuItem setShowAsActionFlags(int actionEnum); 650 651 /** 652 * Set an action view for this menu item. An action view will be displayed in place 653 * of an automatically generated menu item element in the UI when this item is shown 654 * as an action within a parent. 655 * <p> 656 * <strong>Note:</strong> Setting an action view overrides the action provider 657 * set via {@link #setActionProvider(ActionProvider)}. 658 * </p> 659 * 660 * @param view View to use for presenting this item to the user. 661 * @return This Item so additional setters can be called. 662 * 663 * @see #setShowAsAction(int) 664 */ setActionView(View view)665 public MenuItem setActionView(View view); 666 667 /** 668 * Set an action view for this menu item. An action view will be displayed in place 669 * of an automatically generated menu item element in the UI when this item is shown 670 * as an action within a parent. 671 * <p> 672 * <strong>Note:</strong> Setting an action view overrides the action provider 673 * set via {@link #setActionProvider(ActionProvider)}. 674 * </p> 675 * 676 * @param resId Layout resource to use for presenting this item to the user. 677 * @return This Item so additional setters can be called. 678 * 679 * @see #setShowAsAction(int) 680 */ setActionView(@ayoutRes int resId)681 public MenuItem setActionView(@LayoutRes int resId); 682 683 /** 684 * Returns the currently set action view for this menu item. 685 * 686 * @return This item's action view 687 * 688 * @see #setActionView(View) 689 * @see #setShowAsAction(int) 690 */ getActionView()691 public View getActionView(); 692 693 /** 694 * Sets the {@link ActionProvider} responsible for creating an action view if 695 * the item is placed on the action bar. The provider also provides a default 696 * action invoked if the item is placed in the overflow menu. 697 * <p> 698 * <strong>Note:</strong> Setting an action provider overrides the action view 699 * set via {@link #setActionView(int)} or {@link #setActionView(View)}. 700 * </p> 701 * 702 * @param actionProvider The action provider. 703 * @return This Item so additional setters can be called. 704 * 705 * @see ActionProvider 706 */ setActionProvider(ActionProvider actionProvider)707 public MenuItem setActionProvider(ActionProvider actionProvider); 708 709 /** 710 * Gets the {@link ActionProvider}. 711 * 712 * @return The action provider. 713 * 714 * @see ActionProvider 715 * @see #setActionProvider(ActionProvider) 716 */ getActionProvider()717 public ActionProvider getActionProvider(); 718 719 /** 720 * Expand the action view associated with this menu item. 721 * The menu item must have an action view set, as well as 722 * the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. 723 * If a listener has been set using {@link #setOnActionExpandListener(OnActionExpandListener)} 724 * it will have its {@link OnActionExpandListener#onMenuItemActionExpand(MenuItem)} 725 * method invoked. The listener may return false from this method to prevent expanding 726 * the action view. 727 * 728 * @return true if the action view was expanded, false otherwise. 729 */ expandActionView()730 public boolean expandActionView(); 731 732 /** 733 * Collapse the action view associated with this menu item. 734 * The menu item must have an action view set, as well as the showAsAction flag 735 * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a listener has been set using 736 * {@link #setOnActionExpandListener(OnActionExpandListener)} it will have its 737 * {@link OnActionExpandListener#onMenuItemActionCollapse(MenuItem)} method invoked. 738 * The listener may return false from this method to prevent collapsing the action view. 739 * 740 * @return true if the action view was collapsed, false otherwise. 741 */ collapseActionView()742 public boolean collapseActionView(); 743 744 /** 745 * Returns true if this menu item's action view has been expanded. 746 * 747 * @return true if the item's action view is expanded, false otherwise. 748 * 749 * @see #expandActionView() 750 * @see #collapseActionView() 751 * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW 752 * @see OnActionExpandListener 753 */ isActionViewExpanded()754 public boolean isActionViewExpanded(); 755 756 /** 757 * Set an {@link OnActionExpandListener} on this menu item to be notified when 758 * the associated action view is expanded or collapsed. The menu item must 759 * be configured to expand or collapse its action view using the flag 760 * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. 761 * 762 * @param listener Listener that will respond to expand/collapse events 763 * @return This menu item instance for call chaining 764 */ setOnActionExpandListener(OnActionExpandListener listener)765 public MenuItem setOnActionExpandListener(OnActionExpandListener listener); 766 767 /** 768 * Change the content description associated with this menu item. 769 * 770 * @param contentDescription The new content description. 771 */ setContentDescription(CharSequence contentDescription)772 default MenuItem setContentDescription(CharSequence contentDescription) { 773 return this; 774 } 775 776 /** 777 * Retrieve the content description associated with this menu item. 778 * 779 * @return The content description. 780 */ getContentDescription()781 default CharSequence getContentDescription() { 782 return null; 783 } 784 785 /** 786 * Change the tooltip text associated with this menu item. 787 * 788 * @param tooltipText The new tooltip text. 789 */ setTooltipText(CharSequence tooltipText)790 default MenuItem setTooltipText(CharSequence tooltipText) { 791 return this; 792 } 793 794 /** 795 * Retrieve the tooltip text associated with this menu item. 796 * 797 * @return The tooltip text. 798 */ getTooltipText()799 default CharSequence getTooltipText() { 800 return null; 801 } 802 803 /** 804 * Returns true if {@link #setShowAsAction(int)} was set to {@link #SHOW_AS_ACTION_ALWAYS}. 805 * Default value is {@code false}. 806 * 807 * @hide 808 */ requiresActionButton()809 default boolean requiresActionButton() { 810 return false; 811 } 812 813 /** 814 * Returns true if {@link #setShowAsAction(int)} was set to {@link #SHOW_AS_ACTION_NEVER}. 815 * Default value is {@code true}. 816 * 817 * @hide 818 */ requiresOverflow()819 default boolean requiresOverflow() { 820 return true; 821 } 822 } 823