/*
* 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.smartandroid.sa.sherlock.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);
}