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.StringRes; 22 import android.app.Activity; 23 import android.content.Intent; 24 import android.graphics.drawable.Drawable; 25 import android.view.ContextMenu.ContextMenuInfo; 26 import android.view.View.OnCreateContextMenuListener; 27 28 /** 29 * Interface for direct access to a previously created menu item. 30 * <p> 31 * An Item is returned by calling one of the {@link android.view.Menu#add} 32 * methods. 33 * <p> 34 * For a feature set of specific menu types, see {@link Menu}. 35 * 36 * <div class="special reference"> 37 * <h3>Developer Guides</h3> 38 * <p>For information about creating menus, read the 39 * <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide.</p> 40 * </div> 41 */ 42 public interface MenuItem { 43 /* 44 * These should be kept in sync with attrs.xml enum constants for showAsAction 45 */ 46 /** Never show this item as a button in an Action Bar. */ 47 public static final int SHOW_AS_ACTION_NEVER = 0; 48 /** Show this item as a button in an Action Bar if the system decides there is room for it. */ 49 public static final int SHOW_AS_ACTION_IF_ROOM = 1; 50 /** 51 * Always show this item as a button in an Action Bar. 52 * Use sparingly! If too many items are set to always show in the Action Bar it can 53 * crowd the Action Bar and degrade the user experience on devices with smaller screens. 54 * A good rule of thumb is to have no more than 2 items set to always show at a time. 55 */ 56 public static final int SHOW_AS_ACTION_ALWAYS = 2; 57 58 /** 59 * When this item is in the action bar, always show it with a text label even if 60 * it also has an icon specified. 61 */ 62 public static final int SHOW_AS_ACTION_WITH_TEXT = 4; 63 64 /** 65 * This item's action view collapses to a normal menu item. 66 * When expanded, the action view temporarily takes over 67 * a larger segment of its container. 68 */ 69 public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8; 70 71 /** 72 * Interface definition for a callback to be invoked when a menu item is 73 * clicked. 74 * 75 * @see Activity#onContextItemSelected(MenuItem) 76 * @see Activity#onOptionsItemSelected(MenuItem) 77 */ 78 public interface OnMenuItemClickListener { 79 /** 80 * Called when a menu item has been invoked. This is the first code 81 * that is executed; if it returns true, no other callbacks will be 82 * executed. 83 * 84 * @param item The menu item that was invoked. 85 * 86 * @return Return true to consume this click and prevent others from 87 * executing. 88 */ onMenuItemClick(MenuItem item)89 public boolean onMenuItemClick(MenuItem item); 90 } 91 92 /** 93 * Interface definition for a callback to be invoked when a menu item 94 * marked with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} is 95 * expanded or collapsed. 96 * 97 * @see MenuItem#expandActionView() 98 * @see MenuItem#collapseActionView() 99 * @see MenuItem#setShowAsActionFlags(int) 100 */ 101 public interface OnActionExpandListener { 102 /** 103 * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} 104 * is expanded. 105 * @param item Item that was expanded 106 * @return true if the item should expand, false if expansion should be suppressed. 107 */ onMenuItemActionExpand(MenuItem item)108 public boolean onMenuItemActionExpand(MenuItem item); 109 110 /** 111 * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} 112 * is collapsed. 113 * @param item Item that was collapsed 114 * @return true if the item should collapse, false if collapsing should be suppressed. 115 */ onMenuItemActionCollapse(MenuItem item)116 public boolean onMenuItemActionCollapse(MenuItem item); 117 } 118 119 /** 120 * Return the identifier for this menu item. The identifier can not 121 * be changed after the menu is created. 122 * 123 * @return The menu item's identifier. 124 */ getItemId()125 public int getItemId(); 126 127 /** 128 * Return the group identifier that this menu item is part of. The group 129 * identifier can not be changed after the menu is created. 130 * 131 * @return The menu item's group identifier. 132 */ getGroupId()133 public int getGroupId(); 134 135 /** 136 * Return the category and order within the category of this item. This 137 * item will be shown before all items (within its category) that have 138 * order greater than this value. 139 * <p> 140 * An order integer contains the item's category (the upper bits of the 141 * integer; set by or/add the category with the order within the 142 * category) and the ordering of the item within that category (the 143 * lower bits). Example categories are {@link Menu#CATEGORY_SYSTEM}, 144 * {@link Menu#CATEGORY_SECONDARY}, {@link Menu#CATEGORY_ALTERNATIVE}, 145 * {@link Menu#CATEGORY_CONTAINER}. See {@link Menu} for a full list. 146 * 147 * @return The order of this item. 148 */ getOrder()149 public int getOrder(); 150 151 /** 152 * Change the title associated with this item. 153 * 154 * @param title The new text to be displayed. 155 * @return This Item so additional setters can be called. 156 */ setTitle(CharSequence title)157 public MenuItem setTitle(CharSequence title); 158 159 /** 160 * Change the title associated with this item. 161 * <p> 162 * Some menu types do not sufficient space to show the full title, and 163 * instead a condensed title is preferred. See {@link Menu} for more 164 * information. 165 * 166 * @param title The resource id of the new text to be displayed. 167 * @return This Item so additional setters can be called. 168 * @see #setTitleCondensed(CharSequence) 169 */ 170 setTitle(@tringRes int title)171 public MenuItem setTitle(@StringRes int title); 172 173 /** 174 * Retrieve the current title of the item. 175 * 176 * @return The title. 177 */ getTitle()178 public CharSequence getTitle(); 179 180 /** 181 * Change the condensed title associated with this item. The condensed 182 * title is used in situations where the normal title may be too long to 183 * be displayed. 184 * 185 * @param title The new text to be displayed as the condensed title. 186 * @return This Item so additional setters can be called. 187 */ setTitleCondensed(CharSequence title)188 public MenuItem setTitleCondensed(CharSequence title); 189 190 /** 191 * Retrieve the current condensed title of the item. If a condensed 192 * title was never set, it will return the normal title. 193 * 194 * @return The condensed title, if it exists. 195 * Otherwise the normal title. 196 */ getTitleCondensed()197 public CharSequence getTitleCondensed(); 198 199 /** 200 * Change the icon associated with this item. This icon will not always be 201 * shown, so the title should be sufficient in describing this item. See 202 * {@link Menu} for the menu types that support icons. 203 * 204 * @param icon The new icon (as a Drawable) to be displayed. 205 * @return This Item so additional setters can be called. 206 */ setIcon(Drawable icon)207 public MenuItem setIcon(Drawable icon); 208 209 /** 210 * Change the icon associated with this item. This icon will not always be 211 * shown, so the title should be sufficient in describing this item. See 212 * {@link Menu} for the menu types that support icons. 213 * <p> 214 * This method will set the resource ID of the icon which will be used to 215 * lazily get the Drawable when this item is being shown. 216 * 217 * @param iconRes The new icon (as a resource ID) to be displayed. 218 * @return This Item so additional setters can be called. 219 */ setIcon(@rawableRes int iconRes)220 public MenuItem setIcon(@DrawableRes int iconRes); 221 222 /** 223 * Returns the icon for this item as a Drawable (getting it from resources if it hasn't been 224 * loaded before). 225 * 226 * @return The icon as a Drawable. 227 */ getIcon()228 public Drawable getIcon(); 229 230 /** 231 * Change the Intent associated with this item. By default there is no 232 * Intent associated with a menu item. If you set one, and nothing 233 * else handles the item, then the default behavior will be to call 234 * {@link android.content.Context#startActivity} with the given Intent. 235 * 236 * <p>Note that setIntent() can not be used with the versions of 237 * {@link Menu#add} that take a Runnable, because {@link Runnable#run} 238 * does not return a value so there is no way to tell if it handled the 239 * item. In this case it is assumed that the Runnable always handles 240 * the item, and the intent will never be started. 241 * 242 * @see #getIntent 243 * @param intent The Intent to associated with the item. This Intent 244 * object is <em>not</em> copied, so be careful not to 245 * modify it later. 246 * @return This Item so additional setters can be called. 247 */ setIntent(Intent intent)248 public MenuItem setIntent(Intent intent); 249 250 /** 251 * Return the Intent associated with this item. This returns a 252 * reference to the Intent which you can change as desired to modify 253 * what the Item is holding. 254 * 255 * @see #setIntent 256 * @return Returns the last value supplied to {@link #setIntent}, or 257 * null. 258 */ getIntent()259 public Intent getIntent(); 260 261 /** 262 * Change both the numeric and alphabetic shortcut associated with this 263 * item. Note that the shortcut will be triggered when the key that 264 * generates the given character is pressed along with the ctrl key. 265 * Also note that case is not significant and that alphabetic shortcut 266 * characters will be displayed in lower case. 267 * <p> 268 * See {@link Menu} for the menu types that support shortcuts. 269 * 270 * @param numericChar The numeric shortcut key. This is the shortcut when 271 * using a numeric (e.g., 12-key) keyboard. 272 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 273 * using a keyboard with alphabetic keys. 274 * @return This Item so additional setters can be called. 275 */ setShortcut(char numericChar, char alphaChar)276 public MenuItem setShortcut(char numericChar, char alphaChar); 277 278 /** 279 * Change the numeric shortcut associated with this item. 280 * <p> 281 * See {@link Menu} for the menu types that support shortcuts. 282 * 283 * @param numericChar The numeric shortcut key. This is the shortcut when 284 * using a 12-key (numeric) keyboard. 285 * @return This Item so additional setters can be called. 286 */ setNumericShortcut(char numericChar)287 public MenuItem setNumericShortcut(char numericChar); 288 289 /** 290 * Return the char for this menu item's numeric (12-key) shortcut. 291 * 292 * @return Numeric character to use as a shortcut. 293 */ getNumericShortcut()294 public char getNumericShortcut(); 295 296 /** 297 * Change the alphabetic shortcut associated with this item. The shortcut 298 * will be triggered when the key that generates the given character is 299 * pressed along with the ctrl key. Case is not significant and shortcut 300 * characters will be displayed in lower case. Note that menu items with 301 * the characters '\b' or '\n' as shortcuts will get triggered by the 302 * Delete key or Carriage Return key, respectively. 303 * <p> 304 * See {@link Menu} for the menu types that support shortcuts. 305 * 306 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 307 * using a keyboard with alphabetic keys. 308 * @return This Item so additional setters can be called. 309 */ setAlphabeticShortcut(char alphaChar)310 public MenuItem setAlphabeticShortcut(char alphaChar); 311 312 /** 313 * Return the char for this menu item's alphabetic shortcut. 314 * 315 * @return Alphabetic character to use as a shortcut. 316 */ getAlphabeticShortcut()317 public char getAlphabeticShortcut(); 318 319 /** 320 * Control whether this item can display a check mark. Setting this does 321 * not actually display a check mark (see {@link #setChecked} for that); 322 * rather, it ensures there is room in the item in which to display a 323 * check mark. 324 * <p> 325 * See {@link Menu} for the menu types that support check marks. 326 * 327 * @param checkable Set to true to allow a check mark, false to 328 * disallow. The default is false. 329 * @see #setChecked 330 * @see #isCheckable 331 * @see Menu#setGroupCheckable 332 * @return This Item so additional setters can be called. 333 */ setCheckable(boolean checkable)334 public MenuItem setCheckable(boolean checkable); 335 336 /** 337 * Return whether the item can currently display a check mark. 338 * 339 * @return If a check mark can be displayed, returns true. 340 * 341 * @see #setCheckable 342 */ isCheckable()343 public boolean isCheckable(); 344 345 /** 346 * Control whether this item is shown with a check mark. Note that you 347 * must first have enabled checking with {@link #setCheckable} or else 348 * the check mark will not appear. If this item is a member of a group that contains 349 * mutually-exclusive items (set via {@link Menu#setGroupCheckable(int, boolean, boolean)}, 350 * the other items in the group will be unchecked. 351 * <p> 352 * See {@link Menu} for the menu types that support check marks. 353 * 354 * @see #setCheckable 355 * @see #isChecked 356 * @see Menu#setGroupCheckable 357 * @param checked Set to true to display a check mark, false to hide 358 * it. The default value is false. 359 * @return This Item so additional setters can be called. 360 */ setChecked(boolean checked)361 public MenuItem setChecked(boolean checked); 362 363 /** 364 * Return whether the item is currently displaying a check mark. 365 * 366 * @return If a check mark is displayed, returns true. 367 * 368 * @see #setChecked 369 */ isChecked()370 public boolean isChecked(); 371 372 /** 373 * Sets the visibility of the menu item. Even if a menu item is not visible, 374 * it may still be invoked via its shortcut (to completely disable an item, 375 * set it to invisible and {@link #setEnabled(boolean) disabled}). 376 * 377 * @param visible If true then the item will be visible; if false it is 378 * hidden. 379 * @return This Item so additional setters can be called. 380 */ setVisible(boolean visible)381 public MenuItem setVisible(boolean visible); 382 383 /** 384 * Return the visibility of the menu item. 385 * 386 * @return If true the item is visible; else it is hidden. 387 */ isVisible()388 public boolean isVisible(); 389 390 /** 391 * Sets whether the menu item is enabled. Disabling a menu item will not 392 * allow it to be invoked via its shortcut. The menu item will still be 393 * visible. 394 * 395 * @param enabled If true then the item will be invokable; if false it is 396 * won't be invokable. 397 * @return This Item so additional setters can be called. 398 */ setEnabled(boolean enabled)399 public MenuItem setEnabled(boolean enabled); 400 401 /** 402 * Return the enabled state of the menu item. 403 * 404 * @return If true the item is enabled and hence invokable; else it is not. 405 */ isEnabled()406 public boolean isEnabled(); 407 408 /** 409 * Check whether this item has an associated sub-menu. I.e. it is a 410 * sub-menu of another menu. 411 * 412 * @return If true this item has a menu; else it is a 413 * normal item. 414 */ hasSubMenu()415 public boolean hasSubMenu(); 416 417 /** 418 * Get the sub-menu to be invoked when this item is selected, if it has 419 * one. See {@link #hasSubMenu()}. 420 * 421 * @return The associated menu if there is one, else null 422 */ getSubMenu()423 public SubMenu getSubMenu(); 424 425 /** 426 * Set a custom listener for invocation of this menu item. In most 427 * situations, it is more efficient and easier to use 428 * {@link Activity#onOptionsItemSelected(MenuItem)} or 429 * {@link Activity#onContextItemSelected(MenuItem)}. 430 * 431 * @param menuItemClickListener The object to receive invokations. 432 * @return This Item so additional setters can be called. 433 * @see Activity#onOptionsItemSelected(MenuItem) 434 * @see Activity#onContextItemSelected(MenuItem) 435 */ setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener)436 public MenuItem setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener); 437 438 /** 439 * Gets the extra information linked to this menu item. This extra 440 * information is set by the View that added this menu item to the 441 * menu. 442 * 443 * @see OnCreateContextMenuListener 444 * @return The extra information linked to the View that added this 445 * menu item to the menu. This can be null. 446 */ getMenuInfo()447 public ContextMenuInfo getMenuInfo(); 448 449 /** 450 * Sets how this item should display in the presence of an Action Bar. 451 * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, 452 * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should 453 * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. 454 * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, 455 * it should be shown with a text label. 456 * 457 * @param actionEnum How the item should display. One of 458 * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or 459 * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default. 460 * 461 * @see android.app.ActionBar 462 * @see #setActionView(View) 463 */ setShowAsAction(int actionEnum)464 public void setShowAsAction(int actionEnum); 465 466 /** 467 * Sets how this item should display in the presence of an Action Bar. 468 * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, 469 * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should 470 * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. 471 * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, 472 * it should be shown with a text label. 473 * 474 * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it 475 * returns the current MenuItem instance for call chaining. 476 * 477 * @param actionEnum How the item should display. One of 478 * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or 479 * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default. 480 * 481 * @see android.app.ActionBar 482 * @see #setActionView(View) 483 * @return This MenuItem instance for call chaining. 484 */ setShowAsActionFlags(int actionEnum)485 public MenuItem setShowAsActionFlags(int actionEnum); 486 487 /** 488 * Set an action view for this menu item. An action view will be displayed in place 489 * of an automatically generated menu item element in the UI when this item is shown 490 * as an action within a parent. 491 * <p> 492 * <strong>Note:</strong> Setting an action view overrides the action provider 493 * set via {@link #setActionProvider(ActionProvider)}. 494 * </p> 495 * 496 * @param view View to use for presenting this item to the user. 497 * @return This Item so additional setters can be called. 498 * 499 * @see #setShowAsAction(int) 500 */ setActionView(View view)501 public MenuItem setActionView(View view); 502 503 /** 504 * Set an action view for this menu item. An action view will be displayed in place 505 * of an automatically generated menu item element in the UI when this item is shown 506 * as an action within a parent. 507 * <p> 508 * <strong>Note:</strong> Setting an action view overrides the action provider 509 * set via {@link #setActionProvider(ActionProvider)}. 510 * </p> 511 * 512 * @param resId Layout resource to use for presenting this item to the user. 513 * @return This Item so additional setters can be called. 514 * 515 * @see #setShowAsAction(int) 516 */ setActionView(@ayoutRes int resId)517 public MenuItem setActionView(@LayoutRes int resId); 518 519 /** 520 * Returns the currently set action view for this menu item. 521 * 522 * @return This item's action view 523 * 524 * @see #setActionView(View) 525 * @see #setShowAsAction(int) 526 */ getActionView()527 public View getActionView(); 528 529 /** 530 * Sets the {@link ActionProvider} responsible for creating an action view if 531 * the item is placed on the action bar. The provider also provides a default 532 * action invoked if the item is placed in the overflow menu. 533 * <p> 534 * <strong>Note:</strong> Setting an action provider overrides the action view 535 * set via {@link #setActionView(int)} or {@link #setActionView(View)}. 536 * </p> 537 * 538 * @param actionProvider The action provider. 539 * @return This Item so additional setters can be called. 540 * 541 * @see ActionProvider 542 */ setActionProvider(ActionProvider actionProvider)543 public MenuItem setActionProvider(ActionProvider actionProvider); 544 545 /** 546 * Gets the {@link ActionProvider}. 547 * 548 * @return The action provider. 549 * 550 * @see ActionProvider 551 * @see #setActionProvider(ActionProvider) 552 */ getActionProvider()553 public ActionProvider getActionProvider(); 554 555 /** 556 * Expand the action view associated with this menu item. 557 * The menu item must have an action view set, as well as 558 * the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. 559 * If a listener has been set using {@link #setOnActionExpandListener(OnActionExpandListener)} 560 * it will have its {@link OnActionExpandListener#onMenuItemActionExpand(MenuItem)} 561 * method invoked. The listener may return false from this method to prevent expanding 562 * the action view. 563 * 564 * @return true if the action view was expanded, false otherwise. 565 */ expandActionView()566 public boolean expandActionView(); 567 568 /** 569 * Collapse the action view associated with this menu item. 570 * The menu item must have an action view set, as well as the showAsAction flag 571 * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a listener has been set using 572 * {@link #setOnActionExpandListener(OnActionExpandListener)} it will have its 573 * {@link OnActionExpandListener#onMenuItemActionCollapse(MenuItem)} method invoked. 574 * The listener may return false from this method to prevent collapsing the action view. 575 * 576 * @return true if the action view was collapsed, false otherwise. 577 */ collapseActionView()578 public boolean collapseActionView(); 579 580 /** 581 * Returns true if this menu item's action view has been expanded. 582 * 583 * @return true if the item's action view is expanded, false otherwise. 584 * 585 * @see #expandActionView() 586 * @see #collapseActionView() 587 * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW 588 * @see OnActionExpandListener 589 */ isActionViewExpanded()590 public boolean isActionViewExpanded(); 591 592 /** 593 * Set an {@link OnActionExpandListener} on this menu item to be notified when 594 * the associated action view is expanded or collapsed. The menu item must 595 * be configured to expand or collapse its action view using the flag 596 * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. 597 * 598 * @param listener Listener that will respond to expand/collapse events 599 * @return This menu item instance for call chaining 600 */ setOnActionExpandListener(OnActionExpandListener listener)601 public MenuItem setOnActionExpandListener(OnActionExpandListener listener); 602 } 603