Java Source Code: com.actionbarsherlock.view.Menu

/* * 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 com.actionbarsherlock.view; 
 
import android.app.Activity; 
import android.content.ComponentName; 
import android.content.Intent; 
import android.view.KeyEvent; 
 
/** * 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; 
 
    /**     * 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(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, 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(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, 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); 
}