core/java/android/view/MenuItem.java

   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          */
  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          */
 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          */
 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      */
 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      */
 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      */
 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      */
 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
 179     public MenuItem setTitle(@StringRes int title);
 180
 181     /**
 182      * Retrieve the current title of the item.
 183      *
 184      * @return The title.
 185      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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
 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      */
 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
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 814     default boolean requiresOverflow() {
 815         return false;
 816     }
 817 }