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}