| /* |
| * Copyright (C) 2006 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.view; |
| |
| import android.annotation.StringRes; |
| import android.app.Activity; |
| import android.content.ComponentName; |
| import android.content.Intent; |
| |
| /** |
| * Interface for managing the items in a menu. |
| * <p> |
| * By default, every Activity supports an options menu of actions or options. |
| * You can add items to this menu and handle clicks on your additions. The |
| * easiest way of adding menu items is inflating an XML file into the |
| * {@link Menu} via {@link MenuInflater}. The easiest way of attaching code to |
| * clicks is via {@link Activity#onOptionsItemSelected(MenuItem)} and |
| * {@link Activity#onContextItemSelected(MenuItem)}. |
| * <p> |
| * Different menu types support different features: |
| * <ol> |
| * <li><b>Context menus</b>: Do not support item shortcuts and item icons. |
| * <li><b>Options menus</b>: The <b>icon menus</b> do not support item check |
| * marks and only show the item's |
| * {@link MenuItem#setTitleCondensed(CharSequence) condensed title}. The |
| * <b>expanded menus</b> (only available if six or more menu items are visible, |
| * reached via the 'More' item in the icon menu) do not show item icons, and |
| * item check marks are discouraged. |
| * <li><b>Sub menus</b>: Do not support item icons, or nested sub menus. |
| * </ol> |
| * |
| * <div class="special reference"> |
| * <h3>Developer Guides</h3> |
| * <p>For more information about creating menus, read the |
| * <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide.</p> |
| * </div> |
| */ |
| public interface Menu { |
| |
| /** |
| * This is the part of an order integer that the user can provide. |
| * @hide |
| */ |
| static final int USER_MASK = 0x0000ffff; |
| /** |
| * Bit shift of the user portion of the order integer. |
| * @hide |
| */ |
| static final int USER_SHIFT = 0; |
| |
| /** |
| * This is the part of an order integer that supplies the category of the |
| * item. |
| * @hide |
| */ |
| static final int CATEGORY_MASK = 0xffff0000; |
| /** |
| * Bit shift of the category portion of the order integer. |
| * @hide |
| */ |
| static final int CATEGORY_SHIFT = 16; |
| |
| /** |
| * A mask of all supported modifiers for MenuItem's keyboard shortcuts |
| */ |
| static final int SUPPORTED_MODIFIERS_MASK = KeyEvent.META_META_ON | KeyEvent.META_CTRL_ON |
| | KeyEvent.META_ALT_ON | KeyEvent.META_SHIFT_ON | KeyEvent.META_SYM_ON |
| | KeyEvent.META_FUNCTION_ON; |
| |
| /** |
| * Value to use for group and item identifier integers when you don't care |
| * about them. |
| */ |
| static final int NONE = 0; |
| |
| /** |
| * First value for group and item identifier integers. |
| */ |
| static final int FIRST = 1; |
| |
| // Implementation note: Keep these CATEGORY_* in sync with the category enum |
| // in attrs.xml |
| |
| /** |
| * Category code for the order integer for items/groups that are part of a |
| * container -- or/add this with your base value. |
| */ |
| static final int CATEGORY_CONTAINER = 0x00010000; |
| |
| /** |
| * Category code for the order integer for items/groups that are provided by |
| * the system -- or/add this with your base value. |
| */ |
| static final int CATEGORY_SYSTEM = 0x00020000; |
| |
| /** |
| * Category code for the order integer for items/groups that are |
| * user-supplied secondary (infrequently used) options -- or/add this with |
| * your base value. |
| */ |
| static final int CATEGORY_SECONDARY = 0x00030000; |
| |
| /** |
| * Category code for the order integer for items/groups that are |
| * alternative actions on the data that is currently displayed -- or/add |
| * this with your base value. |
| */ |
| static final int CATEGORY_ALTERNATIVE = 0x00040000; |
| |
| /** |
| * Flag for {@link #addIntentOptions}: if set, do not automatically remove |
| * any existing menu items in the same group. |
| */ |
| static final int FLAG_APPEND_TO_GROUP = 0x0001; |
| |
| /** |
| * Flag for {@link #performShortcut}: if set, do not close the menu after |
| * executing the shortcut. |
| */ |
| static final int FLAG_PERFORM_NO_CLOSE = 0x0001; |
| |
| /** |
| * Flag for {@link #performShortcut(int, KeyEvent, int)}: if set, always |
| * close the menu after executing the shortcut. Closing the menu also resets |
| * the prepared state. |
| */ |
| static final int FLAG_ALWAYS_PERFORM_CLOSE = 0x0002; |
| |
| /** |
| * Add a new item to the menu. This item displays the given title for its |
| * label. |
| * |
| * @param title The text to display for the item. |
| * @return The newly added menu item. |
| */ |
| public MenuItem add(CharSequence title); |
| |
| /** |
| * Add a new item to the menu. This item displays the given title for its |
| * label. |
| * |
| * @param titleRes Resource identifier of title string. |
| * @return The newly added menu item. |
| */ |
| public MenuItem add(@StringRes int titleRes); |
| |
| /** |
| * Add a new item to the menu. This item displays the given title for its |
| * label. |
| * |
| * @param groupId The group identifier that this item should be part of. |
| * This can be used to define groups of items for batch state |
| * changes. Normally use {@link #NONE} if an item should not be in a |
| * group. |
| * @param itemId Unique item ID. Use {@link #NONE} if you do not need a |
| * unique ID. |
| * @param order The order for the item. Use {@link #NONE} if you do not care |
| * about the order. See {@link MenuItem#getOrder()}. |
| * @param title The text to display for the item. |
| * @return The newly added menu item. |
| */ |
| public MenuItem add(int groupId, int itemId, int order, CharSequence title); |
| |
| /** |
| * Variation on {@link #add(int, int, int, CharSequence)} that takes a |
| * string resource identifier instead of the string itself. |
| * |
| * @param groupId The group identifier that this item should be part of. |
| * This can also be used to define groups of items for batch state |
| * changes. Normally use {@link #NONE} if an item should not be in a |
| * group. |
| * @param itemId Unique item ID. Use {@link #NONE} if you do not need a |
| * unique ID. |
| * @param order The order for the item. Use {@link #NONE} if you do not care |
| * about the order. See {@link MenuItem#getOrder()}. |
| * @param titleRes Resource identifier of title string. |
| * @return The newly added menu item. |
| */ |
| public MenuItem add(int groupId, int itemId, int order, @StringRes int titleRes); |
| |
| /** |
| * Add a new sub-menu to the menu. This item displays the given title for |
| * its label. To modify other attributes on the submenu's menu item, use |
| * {@link SubMenu#getItem()}. |
| * |
| * @param title The text to display for the item. |
| * @return The newly added sub-menu |
| */ |
| SubMenu addSubMenu(final CharSequence title); |
| |
| /** |
| * Add a new sub-menu to the menu. This item displays the given title for |
| * its label. To modify other attributes on the submenu's menu item, use |
| * {@link SubMenu#getItem()}. |
| * |
| * @param titleRes Resource identifier of title string. |
| * @return The newly added sub-menu |
| */ |
| SubMenu addSubMenu(@StringRes final int titleRes); |
| |
| /** |
| * Add a new sub-menu to the menu. This item displays the given |
| * <var>title</var> for its label. To modify other attributes on the |
| * submenu's menu item, use {@link SubMenu#getItem()}. |
| *<p> |
| * Note that you can only have one level of sub-menus, i.e. you cannnot add |
| * a subMenu to a subMenu: An {@link UnsupportedOperationException} will be |
| * thrown if you try. |
| * |
| * @param groupId The group identifier that this item should be part of. |
| * This can also be used to define groups of items for batch state |
| * changes. Normally use {@link #NONE} if an item should not be in a |
| * group. |
| * @param itemId Unique item ID. Use {@link #NONE} if you do not need a |
| * unique ID. |
| * @param order The order for the item. Use {@link #NONE} if you do not care |
| * about the order. See {@link MenuItem#getOrder()}. |
| * @param title The text to display for the item. |
| * @return The newly added sub-menu |
| */ |
| SubMenu addSubMenu(final int groupId, final int itemId, int order, final CharSequence title); |
| |
| /** |
| * Variation on {@link #addSubMenu(int, int, int, CharSequence)} that takes |
| * a string resource identifier for the title instead of the string itself. |
| * |
| * @param groupId The group identifier that this item should be part of. |
| * This can also be used to define groups of items for batch state |
| * changes. Normally use {@link #NONE} if an item should not be in a group. |
| * @param itemId Unique item ID. Use {@link #NONE} if you do not need a unique ID. |
| * @param order The order for the item. Use {@link #NONE} if you do not care about the |
| * order. See {@link MenuItem#getOrder()}. |
| * @param titleRes Resource identifier of title string. |
| * @return The newly added sub-menu |
| */ |
| SubMenu addSubMenu(int groupId, int itemId, int order, @StringRes int titleRes); |
| |
| /** |
| * Add a group of menu items corresponding to actions that can be performed |
| * for a particular Intent. The Intent is most often configured with a null |
| * action, the data that the current activity is working with, and includes |
| * either the {@link Intent#CATEGORY_ALTERNATIVE} or |
| * {@link Intent#CATEGORY_SELECTED_ALTERNATIVE} to find activities that have |
| * said they would like to be included as optional action. You can, however, |
| * use any Intent you want. |
| * |
| * <p> |
| * See {@link android.content.pm.PackageManager#queryIntentActivityOptions} |
| * for more * details on the <var>caller</var>, <var>specifics</var>, and |
| * <var>intent</var> arguments. The list returned by that function is used |
| * to populate the resulting menu items. |
| * |
| * <p> |
| * All of the menu items of possible options for the intent will be added |
| * with the given group and id. You can use the group to control ordering of |
| * the items in relation to other items in the menu. Normally this function |
| * will automatically remove any existing items in the menu in the same |
| * group and place a divider above and below the added items; this behavior |
| * can be modified with the <var>flags</var> parameter. For each of the |
| * generated items {@link MenuItem#setIntent} is called to associate the |
| * appropriate Intent with the item; this means the activity will |
| * automatically be started for you without having to do anything else. |
| * |
| * @param groupId The group identifier that the items should be part of. |
| * This can also be used to define groups of items for batch state |
| * changes. Normally use {@link #NONE} if the items should not be in |
| * a group. |
| * @param itemId Unique item ID. Use {@link #NONE} if you do not need a |
| * unique ID. |
| * @param order The order for the items. Use {@link #NONE} if you do not |
| * care about the order. See {@link MenuItem#getOrder()}. |
| * @param caller The current activity component name as defined by |
| * queryIntentActivityOptions(). |
| * @param specifics Specific items to place first as defined by |
| * queryIntentActivityOptions(). |
| * @param intent Intent describing the kinds of items to populate in the |
| * list as defined by queryIntentActivityOptions(). |
| * @param flags Additional options controlling how the items are added. |
| * @param outSpecificItems Optional array in which to place the menu items |
| * that were generated for each of the <var>specifics</var> that were |
| * requested. Entries may be null if no activity was found for that |
| * specific action. |
| * @return The number of menu items that were added. |
| * |
| * @see #FLAG_APPEND_TO_GROUP |
| * @see MenuItem#setIntent |
| * @see android.content.pm.PackageManager#queryIntentActivityOptions |
| */ |
| public int addIntentOptions(int groupId, int itemId, int order, |
| ComponentName caller, Intent[] specifics, |
| Intent intent, int flags, MenuItem[] outSpecificItems); |
| |
| /** |
| * Remove the item with the given identifier. |
| * |
| * @param id The item to be removed. If there is no item with this |
| * identifier, nothing happens. |
| */ |
| public void removeItem(int id); |
| |
| /** |
| * Remove all items in the given group. |
| * |
| * @param groupId The group to be removed. If there are no items in this |
| * group, nothing happens. |
| */ |
| public void removeGroup(int groupId); |
| |
| /** |
| * Remove all existing items from the menu, leaving it empty as if it had |
| * just been created. |
| */ |
| public void clear(); |
| |
| /** |
| * Control whether a particular group of items can show a check mark. This |
| * is similar to calling {@link MenuItem#setCheckable} on all of the menu items |
| * with the given group identifier, but in addition you can control whether |
| * this group contains a mutually-exclusive set items. This should be called |
| * after the items of the group have been added to the menu. |
| * |
| * @param group The group of items to operate on. |
| * @param checkable Set to true to allow a check mark, false to |
| * disallow. The default is false. |
| * @param exclusive If set to true, only one item in this group can be |
| * checked at a time; checking an item will automatically |
| * uncheck all others in the group. If set to false, each |
| * item can be checked independently of the others. |
| * |
| * @see MenuItem#setCheckable |
| * @see MenuItem#setChecked |
| */ |
| public void setGroupCheckable(int group, boolean checkable, boolean exclusive); |
| |
| /** |
| * Show or hide all menu items that are in the given group. |
| * |
| * @param group The group of items to operate on. |
| * @param visible If true the items are visible, else they are hidden. |
| * |
| * @see MenuItem#setVisible |
| */ |
| public void setGroupVisible(int group, boolean visible); |
| |
| /** |
| * Enable or disable all menu items that are in the given group. |
| * |
| * @param group The group of items to operate on. |
| * @param enabled If true the items will be enabled, else they will be disabled. |
| * |
| * @see MenuItem#setEnabled |
| */ |
| public void setGroupEnabled(int group, boolean enabled); |
| |
| /** |
| * Return whether the menu currently has item items that are visible. |
| * |
| * @return True if there is one or more item visible, |
| * else false. |
| */ |
| public boolean hasVisibleItems(); |
| |
| /** |
| * Return the menu item with a particular identifier. |
| * |
| * @param id The identifier to find. |
| * |
| * @return The menu item object, or null if there is no item with |
| * this identifier. |
| */ |
| public MenuItem findItem(int id); |
| |
| /** |
| * Get the number of items in the menu. Note that this will change any |
| * times items are added or removed from the menu. |
| * |
| * @return The item count. |
| */ |
| public int size(); |
| |
| /** |
| * Gets the menu item at the given index. |
| * |
| * @param index The index of the menu item to return. |
| * @return The menu item. |
| * @exception IndexOutOfBoundsException |
| * when {@code index < 0 || >= size()} |
| */ |
| public MenuItem getItem(int index); |
| |
| /** |
| * Closes the menu, if open. |
| */ |
| public void close(); |
| |
| /** |
| * Execute the menu item action associated with the given shortcut |
| * character. |
| * |
| * @param keyCode The keycode of the shortcut key. |
| * @param event Key event message. |
| * @param flags Additional option flags or 0. |
| * |
| * @return If the given shortcut exists and is shown, returns |
| * true; else returns false. |
| * |
| * @see #FLAG_PERFORM_NO_CLOSE |
| */ |
| public boolean performShortcut(int keyCode, KeyEvent event, int flags); |
| |
| /** |
| * Is a keypress one of the defined shortcut keys for this window. |
| * @param keyCode the key code from {@link KeyEvent} to check. |
| * @param event the {@link KeyEvent} to use to help check. |
| */ |
| boolean isShortcutKey(int keyCode, KeyEvent event); |
| |
| /** |
| * Execute the menu item action associated with the given menu identifier. |
| * |
| * @param id Identifier associated with the menu item. |
| * @param flags Additional option flags or 0. |
| * |
| * @return If the given identifier exists and is shown, returns |
| * true; else returns false. |
| * |
| * @see #FLAG_PERFORM_NO_CLOSE |
| */ |
| public boolean performIdentifierAction(int id, int flags); |
| |
| |
| /** |
| * Control whether the menu should be running in qwerty mode (alphabetic |
| * shortcuts) or 12-key mode (numeric shortcuts). |
| * |
| * @param isQwerty If true the menu will use alphabetic shortcuts; else it |
| * will use numeric shortcuts. |
| */ |
| public void setQwertyMode(boolean isQwerty); |
| |
| /** |
| * Enable or disable the group dividers. |
| */ |
| default void setGroupDividerEnabled(boolean groupDividerEnabled) { |
| } |
| } |