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