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 */
33public interface MenuItem {
34    /**
35     * Interface definition for a callback to be invoked when a menu item is
36     * clicked.
37     *
38     * @see Activity#onContextItemSelected(MenuItem)
39     * @see Activity#onOptionsItemSelected(MenuItem)
40     */
41    public interface OnMenuItemClickListener {
42        /**
43         * Called when a menu item has been invoked.  This is the first code
44         * that is executed; if it returns true, no other callbacks will be
45         * executed.
46         *
47         * @param item The menu item that was invoked.
48         *
49         * @return Return true to consume this click and prevent others from
50         *         executing.
51         */
52        public boolean onMenuItemClick(MenuItem item);
53    }
54
55    /**
56     * Return the identifier for this menu item.  The identifier can not
57     * be changed after the menu is created.
58     *
59     * @return The menu item's identifier.
60     */
61    public int getItemId();
62
63    /**
64     * Return the group identifier that this menu item is part of. The group
65     * identifier can not be changed after the menu is created.
66     *
67     * @return The menu item's group identifier.
68     */
69    public int getGroupId();
70
71    /**
72     * Return the category and order within the category of this item. This
73     * item will be shown before all items (within its category) that have
74     * order greater than this value.
75     * <p>
76     * An order integer contains the item's category (the upper bits of the
77     * integer; set by or/add the category with the order within the
78     * category) and the ordering of the item within that category (the
79     * lower bits). Example categories are {@link Menu#CATEGORY_SYSTEM},
80     * {@link Menu#CATEGORY_SECONDARY}, {@link Menu#CATEGORY_ALTERNATIVE},
81     * {@link Menu#CATEGORY_CONTAINER}. See {@link Menu} for a full list.
82     *
83     * @return The order of this item.
84     */
85    public int getOrder();
86
87    /**
88     * Change the title associated with this item.
89     *
90     * @param title The new text to be displayed.
91     * @return This Item so additional setters can be called.
92     */
93    public MenuItem setTitle(CharSequence title);
94
95    /**
96     * Change the title associated with this item.
97     * <p>
98     * Some menu types do not sufficient space to show the full title, and
99     * instead a condensed title is preferred. See {@link Menu} for more
100     * information.
101     *
102     * @param title The resource id of the new text to be displayed.
103     * @return This Item so additional setters can be called.
104     * @see #setTitleCondensed(CharSequence)
105     */
106
107    public MenuItem setTitle(int title);
108
109    /**
110     * Retrieve the current title of the item.
111     *
112     * @return The title.
113     */
114    public CharSequence getTitle();
115
116    /**
117     * Change the condensed title associated with this item. The condensed
118     * title is used in situations where the normal title may be too long to
119     * be displayed.
120     *
121     * @param title The new text to be displayed as the condensed title.
122     * @return This Item so additional setters can be called.
123     */
124    public MenuItem setTitleCondensed(CharSequence title);
125
126    /**
127     * Retrieve the current condensed title of the item. If a condensed
128     * title was never set, it will return the normal title.
129     *
130     * @return The condensed title, if it exists.
131     *         Otherwise the normal title.
132     */
133    public CharSequence getTitleCondensed();
134
135    /**
136     * Change the icon associated with this item. This icon will not always be
137     * shown, so the title should be sufficient in describing this item. See
138     * {@link Menu} for the menu types that support icons.
139     *
140     * @param icon The new icon (as a Drawable) to be displayed.
141     * @return This Item so additional setters can be called.
142     */
143    public MenuItem setIcon(Drawable icon);
144
145    /**
146     * Change the icon associated with this item. This icon will not always be
147     * shown, so the title should be sufficient in describing this item. See
148     * {@link Menu} for the menu types that support icons.
149     * <p>
150     * This method will set the resource ID of the icon which will be used to
151     * lazily get the Drawable when this item is being shown.
152     *
153     * @param iconRes The new icon (as a resource ID) to be displayed.
154     * @return This Item so additional setters can be called.
155     */
156    public MenuItem setIcon(int iconRes);
157
158    /**
159     * Returns the icon for this item as a Drawable (getting it from resources if it hasn't been
160     * loaded before).
161     *
162     * @return The icon as a Drawable.
163     */
164    public Drawable getIcon();
165
166    /**
167     * Change the Intent associated with this item.  By default there is no
168     * Intent associated with a menu item.  If you set one, and nothing
169     * else handles the item, then the default behavior will be to call
170     * {@link android.content.Context#startActivity} with the given Intent.
171     *
172     * <p>Note that setIntent() can not be used with the versions of
173     * {@link Menu#add} that take a Runnable, because {@link Runnable#run}
174     * does not return a value so there is no way to tell if it handled the
175     * item.  In this case it is assumed that the Runnable always handles
176     * the item, and the intent will never be started.
177     *
178     * @see #getIntent
179     * @param intent The Intent to associated with the item.  This Intent
180     *               object is <em>not</em> copied, so be careful not to
181     *               modify it later.
182     * @return This Item so additional setters can be called.
183     */
184    public MenuItem setIntent(Intent intent);
185
186    /**
187     * Return the Intent associated with this item.  This returns a
188     * reference to the Intent which you can change as desired to modify
189     * what the Item is holding.
190     *
191     * @see #setIntent
192     * @return Returns the last value supplied to {@link #setIntent}, or
193     *         null.
194     */
195    public Intent getIntent();
196
197    /**
198     * Change both the numeric and alphabetic shortcut associated with this
199     * item. Note that the shortcut will be triggered when the key that
200     * generates the given character is pressed alone or along with with the alt
201     * key. Also note that case is not significant and that alphabetic shortcut
202     * characters will be displayed in lower case.
203     * <p>
204     * See {@link Menu} for the menu types that support shortcuts.
205     *
206     * @param numericChar The numeric shortcut key. This is the shortcut when
207     *        using a numeric (e.g., 12-key) keyboard.
208     * @param alphaChar The alphabetic shortcut key. This is the shortcut when
209     *        using a keyboard with alphabetic keys.
210     * @return This Item so additional setters can be called.
211     */
212    public MenuItem setShortcut(char numericChar, char alphaChar);
213
214    /**
215     * Change the numeric shortcut associated with this item.
216     * <p>
217     * See {@link Menu} for the menu types that support shortcuts.
218     *
219     * @param numericChar The numeric shortcut key.  This is the shortcut when
220     *                 using a 12-key (numeric) keyboard.
221     * @return This Item so additional setters can be called.
222     */
223    public MenuItem setNumericShortcut(char numericChar);
224
225    /**
226     * Return the char for this menu item's numeric (12-key) shortcut.
227     *
228     * @return Numeric character to use as a shortcut.
229     */
230    public char getNumericShortcut();
231
232    /**
233     * Change the alphabetic shortcut associated with this item. The shortcut
234     * will be triggered when the key that generates the given character is
235     * pressed alone or along with with the alt key. Case is not significant and
236     * shortcut characters will be displayed in lower case. Note that menu items
237     * with the characters '\b' or '\n' as shortcuts will get triggered by the
238     * Delete key or Carriage Return key, respectively.
239     * <p>
240     * See {@link Menu} for the menu types that support shortcuts.
241     *
242     * @param alphaChar The alphabetic shortcut key. This is the shortcut when
243     *        using a keyboard with alphabetic keys.
244     * @return This Item so additional setters can be called.
245     */
246    public MenuItem setAlphabeticShortcut(char alphaChar);
247
248    /**
249     * Return the char for this menu item's alphabetic shortcut.
250     *
251     * @return Alphabetic character to use as a shortcut.
252     */
253    public char getAlphabeticShortcut();
254
255    /**
256     * Control whether this item can display a check mark. Setting this does
257     * not actually display a check mark (see {@link #setChecked} for that);
258     * rather, it ensures there is room in the item in which to display a
259     * check mark.
260     * <p>
261     * See {@link Menu} for the menu types that support check marks.
262     *
263     * @param checkable Set to true to allow a check mark, false to
264     *            disallow. The default is false.
265     * @see #setChecked
266     * @see #isCheckable
267     * @see Menu#setGroupCheckable
268     * @return This Item so additional setters can be called.
269     */
270    public MenuItem setCheckable(boolean checkable);
271
272    /**
273     * Return whether the item can currently display a check mark.
274     *
275     * @return If a check mark can be displayed, returns true.
276     *
277     * @see #setCheckable
278     */
279    public boolean isCheckable();
280
281    /**
282     * Control whether this item is shown with a check mark.  Note that you
283     * must first have enabled checking with {@link #setCheckable} or else
284     * the check mark will not appear.  If this item is a member of a group that contains
285     * mutually-exclusive items (set via {@link Menu#setGroupCheckable(int, boolean, boolean)},
286     * the other items in the group will be unchecked.
287     * <p>
288     * See {@link Menu} for the menu types that support check marks.
289     *
290     * @see #setCheckable
291     * @see #isChecked
292     * @see Menu#setGroupCheckable
293     * @param checked Set to true to display a check mark, false to hide
294     *                it.  The default value is false.
295     * @return This Item so additional setters can be called.
296     */
297    public MenuItem setChecked(boolean checked);
298
299    /**
300     * Return whether the item is currently displaying a check mark.
301     *
302     * @return If a check mark is displayed, returns true.
303     *
304     * @see #setChecked
305     */
306    public boolean isChecked();
307
308    /**
309     * Sets the visibility of the menu item. Even if a menu item is not visible,
310     * it may still be invoked via its shortcut (to completely disable an item,
311     * set it to invisible and {@link #setEnabled(boolean) disabled}).
312     *
313     * @param visible If true then the item will be visible; if false it is
314     *        hidden.
315     * @return This Item so additional setters can be called.
316     */
317    public MenuItem setVisible(boolean visible);
318
319    /**
320     * Return the visibility of the menu item.
321     *
322     * @return If true the item is visible; else it is hidden.
323     */
324    public boolean isVisible();
325
326    /**
327     * Sets whether the menu item is enabled. Disabling a menu item will not
328     * allow it to be invoked via its shortcut. The menu item will still be
329     * visible.
330     *
331     * @param enabled If true then the item will be invokable; if false it is
332     *        won't be invokable.
333     * @return This Item so additional setters can be called.
334     */
335    public MenuItem setEnabled(boolean enabled);
336
337    /**
338     * Return the enabled state of the menu item.
339     *
340     * @return If true the item is enabled and hence invokable; else it is not.
341     */
342    public boolean isEnabled();
343
344    /**
345     * Check whether this item has an associated sub-menu.  I.e. it is a
346     * sub-menu of another menu.
347     *
348     * @return If true this item has a menu; else it is a
349     *         normal item.
350     */
351    public boolean hasSubMenu();
352
353    /**
354     * Get the sub-menu to be invoked when this item is selected, if it has
355     * one. See {@link #hasSubMenu()}.
356     *
357     * @return The associated menu if there is one, else null
358     */
359    public SubMenu getSubMenu();
360
361    /**
362     * Set a custom listener for invocation of this menu item. In most
363     * situations, it is more efficient and easier to use
364     * {@link Activity#onOptionsItemSelected(MenuItem)} or
365     * {@link Activity#onContextItemSelected(MenuItem)}.
366     *
367     * @param menuItemClickListener The object to receive invokations.
368     * @return This Item so additional setters can be called.
369     * @see Activity#onOptionsItemSelected(MenuItem)
370     * @see Activity#onContextItemSelected(MenuItem)
371     */
372    public MenuItem setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener);
373
374    /**
375     * Gets the extra information linked to this menu item.  This extra
376     * information is set by the View that added this menu item to the
377     * menu.
378     *
379     * @see OnCreateContextMenuListener
380     * @return The extra information linked to the View that added this
381     *         menu item to the menu. This can be null.
382     */
383    public ContextMenuInfo getMenuInfo();
384}