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