2 * Copyright (C) 2008 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package com.actionbarsherlock.view;
19 import android.content.Intent;
20 import android.graphics.drawable.Drawable;
21 import android.view.ContextMenu.ContextMenuInfo;
22 import android.view.View;
25 * Interface for direct access to a previously created menu item.
27 * An Item is returned by calling one of the {@link android.view.Menu#add}
30 * For a feature set of specific menu types, see {@link Menu}.
32 * <div class="special reference">
33 * <h3>Developer Guides</h3>
34 * <p>For information about creating menus, read the
35 * <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide.</p>
38 public interface MenuItem {
40 * These should be kept in sync with attrs.xml enum constants for showAsAction
42 /** Never show this item as a button in an Action Bar. */
43 public static final int SHOW_AS_ACTION_NEVER = android.view.MenuItem.SHOW_AS_ACTION_NEVER;
44 /** Show this item as a button in an Action Bar if the system decides there is room for it. */
45 public static final int SHOW_AS_ACTION_IF_ROOM = android.view.MenuItem.SHOW_AS_ACTION_IF_ROOM;
47 * Always show this item as a button in an Action Bar.
48 * Use sparingly! If too many items are set to always show in the Action Bar it can
49 * crowd the Action Bar and degrade the user experience on devices with smaller screens.
50 * A good rule of thumb is to have no more than 2 items set to always show at a time.
52 public static final int SHOW_AS_ACTION_ALWAYS = android.view.MenuItem.SHOW_AS_ACTION_ALWAYS;
55 * When this item is in the action bar, always show it with a text label even if
56 * it also has an icon specified.
58 public static final int SHOW_AS_ACTION_WITH_TEXT = android.view.MenuItem.SHOW_AS_ACTION_WITH_TEXT;
61 * This item's action view collapses to a normal menu item.
62 * When expanded, the action view temporarily takes over
63 * a larger segment of its container.
65 public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = android.view.MenuItem.SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW;
68 * Interface definition for a callback to be invoked when a menu item is
71 * @see Activity#onContextItemSelected(MenuItem)
72 * @see Activity#onOptionsItemSelected(MenuItem)
74 public interface OnMenuItemClickListener {
76 * Called when a menu item has been invoked. This is the first code
77 * that is executed; if it returns true, no other callbacks will be
80 * @param item The menu item that was invoked.
82 * @return Return true to consume this click and prevent others from
85 public boolean onMenuItemClick(MenuItem item);
89 * Interface definition for a callback to be invoked when a menu item
90 * marked with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} is
91 * expanded or collapsed.
93 * @see MenuItem#expandActionView()
94 * @see MenuItem#collapseActionView()
95 * @see MenuItem#setShowAsActionFlags(int)
97 public interface OnActionExpandListener {
99 * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}
101 * @param item Item that was expanded
102 * @return true if the item should expand, false if expansion should be suppressed.
104 public boolean onMenuItemActionExpand(MenuItem item);
107 * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}
109 * @param item Item that was collapsed
110 * @return true if the item should collapse, false if collapsing should be suppressed.
112 public boolean onMenuItemActionCollapse(MenuItem item);
116 * Return the identifier for this menu item. The identifier can not
117 * be changed after the menu is created.
119 * @return The menu item's identifier.
121 public int getItemId();
124 * Return the group identifier that this menu item is part of. The group
125 * identifier can not be changed after the menu is created.
127 * @return The menu item's group identifier.
129 public int getGroupId();
132 * Return the category and order within the category of this item. This
133 * item will be shown before all items (within its category) that have
134 * order greater than this value.
136 * An order integer contains the item's category (the upper bits of the
137 * integer; set by or/add the category with the order within the
138 * category) and the ordering of the item within that category (the
139 * lower bits). Example categories are {@link Menu#CATEGORY_SYSTEM},
140 * {@link Menu#CATEGORY_SECONDARY}, {@link Menu#CATEGORY_ALTERNATIVE},
141 * {@link Menu#CATEGORY_CONTAINER}. See {@link Menu} for a full list.
143 * @return The order of this item.
145 public int getOrder();
148 * Change the title associated with this item.
150 * @param title The new text to be displayed.
151 * @return This Item so additional setters can be called.
153 public MenuItem setTitle(CharSequence title);
156 * Change the title associated with this item.
158 * Some menu types do not sufficient space to show the full title, and
159 * instead a condensed title is preferred. See {@link Menu} for more
162 * @param title The resource id of the new text to be displayed.
163 * @return This Item so additional setters can be called.
164 * @see #setTitleCondensed(CharSequence)
167 public MenuItem setTitle(int title);
170 * Retrieve the current title of the item.
174 public CharSequence getTitle();
177 * Change the condensed title associated with this item. The condensed
178 * title is used in situations where the normal title may be too long to
181 * @param title The new text to be displayed as the condensed title.
182 * @return This Item so additional setters can be called.
184 public MenuItem setTitleCondensed(CharSequence title);
187 * Retrieve the current condensed title of the item. If a condensed
188 * title was never set, it will return the normal title.
190 * @return The condensed title, if it exists.
191 * Otherwise the normal title.
193 public CharSequence getTitleCondensed();
196 * Change the icon associated with this item. This icon will not always be
197 * shown, so the title should be sufficient in describing this item. See
198 * {@link Menu} for the menu types that support icons.
200 * @param icon The new icon (as a Drawable) to be displayed.
201 * @return This Item so additional setters can be called.
203 public MenuItem setIcon(Drawable icon);
206 * Change the icon associated with this item. This icon will not always be
207 * shown, so the title should be sufficient in describing this item. See
208 * {@link Menu} for the menu types that support icons.
210 * This method will set the resource ID of the icon which will be used to
211 * lazily get the Drawable when this item is being shown.
213 * @param iconRes The new icon (as a resource ID) to be displayed.
214 * @return This Item so additional setters can be called.
216 public MenuItem setIcon(int iconRes);
219 * Returns the icon for this item as a Drawable (getting it from resources if it hasn't been
222 * @return The icon as a Drawable.
224 public Drawable getIcon();
227 * Change the Intent associated with this item. By default there is no
228 * Intent associated with a menu item. If you set one, and nothing
229 * else handles the item, then the default behavior will be to call
230 * {@link android.content.Context#startActivity} with the given Intent.
232 * <p>Note that setIntent() can not be used with the versions of
233 * {@link Menu#add} that take a Runnable, because {@link Runnable#run}
234 * does not return a value so there is no way to tell if it handled the
235 * item. In this case it is assumed that the Runnable always handles
236 * the item, and the intent will never be started.
239 * @param intent The Intent to associated with the item. This Intent
240 * object is <em>not</em> copied, so be careful not to
242 * @return This Item so additional setters can be called.
244 public MenuItem setIntent(Intent intent);
247 * Return the Intent associated with this item. This returns a
248 * reference to the Intent which you can change as desired to modify
249 * what the Item is holding.
252 * @return Returns the last value supplied to {@link #setIntent}, or
255 public Intent getIntent();
258 * Change both the numeric and alphabetic shortcut associated with this
259 * item. Note that the shortcut will be triggered when the key that
260 * generates the given character is pressed alone or along with with the alt
261 * key. Also note that case is not significant and that alphabetic shortcut
262 * characters will be displayed in lower case.
264 * See {@link Menu} for the menu types that support shortcuts.
266 * @param numericChar The numeric shortcut key. This is the shortcut when
267 * using a numeric (e.g., 12-key) keyboard.
268 * @param alphaChar The alphabetic shortcut key. This is the shortcut when
269 * using a keyboard with alphabetic keys.
270 * @return This Item so additional setters can be called.
272 public MenuItem setShortcut(char numericChar, char alphaChar);
275 * Change the numeric shortcut associated with this item.
277 * See {@link Menu} for the menu types that support shortcuts.
279 * @param numericChar The numeric shortcut key. This is the shortcut when
280 * using a 12-key (numeric) keyboard.
281 * @return This Item so additional setters can be called.
283 public MenuItem setNumericShortcut(char numericChar);
286 * Return the char for this menu item's numeric (12-key) shortcut.
288 * @return Numeric character to use as a shortcut.
290 public char getNumericShortcut();
293 * Change the alphabetic shortcut associated with this item. The shortcut
294 * will be triggered when the key that generates the given character is
295 * pressed alone or along with with the alt key. Case is not significant and
296 * shortcut characters will be displayed in lower case. Note that menu items
297 * with the characters '\b' or '\n' as shortcuts will get triggered by the
298 * Delete key or Carriage Return key, respectively.
300 * See {@link Menu} for the menu types that support shortcuts.
302 * @param alphaChar The alphabetic shortcut key. This is the shortcut when
303 * using a keyboard with alphabetic keys.
304 * @return This Item so additional setters can be called.
306 public MenuItem setAlphabeticShortcut(char alphaChar);
309 * Return the char for this menu item's alphabetic shortcut.
311 * @return Alphabetic character to use as a shortcut.
313 public char getAlphabeticShortcut();
316 * Control whether this item can display a check mark. Setting this does
317 * not actually display a check mark (see {@link #setChecked} for that);
318 * rather, it ensures there is room in the item in which to display a
321 * See {@link Menu} for the menu types that support check marks.
323 * @param checkable Set to true to allow a check mark, false to
324 * disallow. The default is false.
327 * @see Menu#setGroupCheckable
328 * @return This Item so additional setters can be called.
330 public MenuItem setCheckable(boolean checkable);
333 * Return whether the item can currently display a check mark.
335 * @return If a check mark can be displayed, returns true.
339 public boolean isCheckable();
342 * Control whether this item is shown with a check mark. Note that you
343 * must first have enabled checking with {@link #setCheckable} or else
344 * the check mark will not appear. If this item is a member of a group that contains
345 * mutually-exclusive items (set via {@link Menu#setGroupCheckable(int, boolean, boolean)},
346 * the other items in the group will be unchecked.
348 * See {@link Menu} for the menu types that support check marks.
352 * @see Menu#setGroupCheckable
353 * @param checked Set to true to display a check mark, false to hide
354 * it. The default value is false.
355 * @return This Item so additional setters can be called.
357 public MenuItem setChecked(boolean checked);
360 * Return whether the item is currently displaying a check mark.
362 * @return If a check mark is displayed, returns true.
366 public boolean isChecked();
369 * Sets the visibility of the menu item. Even if a menu item is not visible,
370 * it may still be invoked via its shortcut (to completely disable an item,
371 * set it to invisible and {@link #setEnabled(boolean) disabled}).
373 * @param visible If true then the item will be visible; if false it is
375 * @return This Item so additional setters can be called.
377 public MenuItem setVisible(boolean visible);
380 * Return the visibility of the menu item.
382 * @return If true the item is visible; else it is hidden.
384 public boolean isVisible();
387 * Sets whether the menu item is enabled. Disabling a menu item will not
388 * allow it to be invoked via its shortcut. The menu item will still be
391 * @param enabled If true then the item will be invokable; if false it is
392 * won't be invokable.
393 * @return This Item so additional setters can be called.
395 public MenuItem setEnabled(boolean enabled);
398 * Return the enabled state of the menu item.
400 * @return If true the item is enabled and hence invokable; else it is not.
402 public boolean isEnabled();
405 * Check whether this item has an associated sub-menu. I.e. it is a
406 * sub-menu of another menu.
408 * @return If true this item has a menu; else it is a
411 public boolean hasSubMenu();
414 * Get the sub-menu to be invoked when this item is selected, if it has
415 * one. See {@link #hasSubMenu()}.
417 * @return The associated menu if there is one, else null
419 public SubMenu getSubMenu();
422 * Set a custom listener for invocation of this menu item. In most
423 * situations, it is more efficient and easier to use
424 * {@link Activity#onOptionsItemSelected(MenuItem)} or
425 * {@link Activity#onContextItemSelected(MenuItem)}.
427 * @param menuItemClickListener The object to receive invokations.
428 * @return This Item so additional setters can be called.
429 * @see Activity#onOptionsItemSelected(MenuItem)
430 * @see Activity#onContextItemSelected(MenuItem)
432 public MenuItem setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener);
435 * Gets the extra information linked to this menu item. This extra
436 * information is set by the View that added this menu item to the
439 * @see OnCreateContextMenuListener
440 * @return The extra information linked to the View that added this
441 * menu item to the menu. This can be null.
443 public ContextMenuInfo getMenuInfo();
446 * Sets how this item should display in the presence of an Action Bar.
447 * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS},
448 * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should
449 * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}.
450 * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action,
451 * it should be shown with a text label.
453 * @param actionEnum How the item should display. One of
454 * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or
455 * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default.
457 * @see android.app.ActionBar
458 * @see #setActionView(View)
460 public void setShowAsAction(int actionEnum);
463 * Sets how this item should display in the presence of an Action Bar.
464 * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS},
465 * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should
466 * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}.
467 * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action,
468 * it should be shown with a text label.
470 * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it
471 * returns the current MenuItem instance for call chaining.
473 * @param actionEnum How the item should display. One of
474 * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or
475 * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default.
477 * @see android.app.ActionBar
478 * @see #setActionView(View)
479 * @return This MenuItem instance for call chaining.
481 public MenuItem setShowAsActionFlags(int actionEnum);
484 * Set an action view for this menu item. An action view will be displayed in place
485 * of an automatically generated menu item element in the UI when this item is shown
486 * as an action within a parent.
488 * <strong>Note:</strong> Setting an action view overrides the action provider
489 * set via {@link #setActionProvider(ActionProvider)}.
492 * @param view View to use for presenting this item to the user.
493 * @return This Item so additional setters can be called.
495 * @see #setShowAsAction(int)
497 public MenuItem setActionView(View view);
500 * Set an action view for this menu item. An action view will be displayed in place
501 * of an automatically generated menu item element in the UI when this item is shown
502 * as an action within a parent.
504 * <strong>Note:</strong> Setting an action view overrides the action provider
505 * set via {@link #setActionProvider(ActionProvider)}.
508 * @param resId Layout resource to use for presenting this item to the user.
509 * @return This Item so additional setters can be called.
511 * @see #setShowAsAction(int)
513 public MenuItem setActionView(int resId);
516 * Returns the currently set action view for this menu item.
518 * @return This item's action view
520 * @see #setActionView(View)
521 * @see #setShowAsAction(int)
523 public View getActionView();
526 * Sets the {@link ActionProvider} responsible for creating an action view if
527 * the item is placed on the action bar. The provider also provides a default
528 * action invoked if the item is placed in the overflow menu.
530 * <strong>Note:</strong> Setting an action provider overrides the action view
531 * set via {@link #setActionView(int)} or {@link #setActionView(View)}.
534 * @param actionProvider The action provider.
535 * @return This Item so additional setters can be called.
537 * @see ActionProvider
539 public MenuItem setActionProvider(ActionProvider actionProvider);
542 * Gets the {@link ActionProvider}.
544 * @return The action provider.
546 * @see ActionProvider
547 * @see #setActionProvider(ActionProvider)
549 public ActionProvider getActionProvider();
552 * Expand the action view associated with this menu item.
553 * The menu item must have an action view set, as well as
554 * the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}.
555 * If a listener has been set using {@link #setOnActionExpandListener(OnActionExpandListener)}
556 * it will have its {@link OnActionExpandListener#onMenuItemActionExpand(MenuItem)}
557 * method invoked. The listener may return false from this method to prevent expanding
560 * @return true if the action view was expanded, false otherwise.
562 public boolean expandActionView();
565 * Collapse the action view associated with this menu item.
566 * The menu item must have an action view set, as well as the showAsAction flag
567 * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a listener has been set using
568 * {@link #setOnActionExpandListener(OnActionExpandListener)} it will have its
569 * {@link OnActionExpandListener#onMenuItemActionCollapse(MenuItem)} method invoked.
570 * The listener may return false from this method to prevent collapsing the action view.
572 * @return true if the action view was collapsed, false otherwise.
574 public boolean collapseActionView();
577 * Returns true if this menu item's action view has been expanded.
579 * @return true if the item's action view is expanded, false otherwise.
581 * @see #expandActionView()
582 * @see #collapseActionView()
583 * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW
584 * @see OnActionExpandListener
586 public boolean isActionViewExpanded();
589 * Set an {@link OnActionExpandListener} on this menu item to be notified when
590 * the associated action view is expanded or collapsed. The menu item must
591 * be configured to expand or collapse its action view using the flag
592 * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}.
594 * @param listener Listener that will respond to expand/collapse events
595 * @return This menu item instance for call chaining
597 public MenuItem setOnActionExpandListener(OnActionExpandListener listener);