1 /* 2 * Copyright (C) 2006 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 17 package android.view; 18 19 import android.annotation.StringRes; 20 import android.app.Activity; 21 import android.content.ComponentName; 22 import android.content.Intent; 23 24 /** 25 * Interface for managing the items in a menu. 26 * <p> 27 * By default, every Activity supports an options menu of actions or options. 28 * You can add items to this menu and handle clicks on your additions. The 29 * easiest way of adding menu items is inflating an XML file into the 30 * {@link Menu} via {@link MenuInflater}. The easiest way of attaching code to 31 * clicks is via {@link Activity#onOptionsItemSelected(MenuItem)} and 32 * {@link Activity#onContextItemSelected(MenuItem)}. 33 * <p> 34 * Different menu types support different features: 35 * <ol> 36 * <li><b>Context menus</b>: Do not support item shortcuts and item icons. 37 * <li><b>Options menus</b>: The <b>icon menus</b> do not support item check 38 * marks and only show the item's 39 * {@link MenuItem#setTitleCondensed(CharSequence) condensed title}. The 40 * <b>expanded menus</b> (only available if six or more menu items are visible, 41 * reached via the 'More' item in the icon menu) do not show item icons, and 42 * item check marks are discouraged. 43 * <li><b>Sub menus</b>: Do not support item icons, or nested sub menus. 44 * </ol> 45 * 46 * <div class="special reference"> 47 * <h3>Developer Guides</h3> 48 * <p>For more information about creating menus, read the 49 * <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide.</p> 50 * </div> 51 */ 52 public interface Menu { 53 54 /** 55 * This is the part of an order integer that the user can provide. 56 * @hide 57 */ 58 static final int USER_MASK = 0x0000ffff; 59 /** 60 * Bit shift of the user portion of the order integer. 61 * @hide 62 */ 63 static final int USER_SHIFT = 0; 64 65 /** 66 * This is the part of an order integer that supplies the category of the 67 * item. 68 * @hide 69 */ 70 static final int CATEGORY_MASK = 0xffff0000; 71 /** 72 * Bit shift of the category portion of the order integer. 73 * @hide 74 */ 75 static final int CATEGORY_SHIFT = 16; 76 77 /** 78 * A mask of all supported modifiers for MenuItem's keyboard shortcuts 79 */ 80 static final int SUPPORTED_MODIFIERS_MASK = KeyEvent.META_META_ON | KeyEvent.META_CTRL_ON 81 | KeyEvent.META_ALT_ON | KeyEvent.META_SHIFT_ON | KeyEvent.META_SYM_ON 82 | KeyEvent.META_FUNCTION_ON; 83 84 /** 85 * Value to use for group and item identifier integers when you don't care 86 * about them. 87 */ 88 static final int NONE = 0; 89 90 /** 91 * First value for group and item identifier integers. 92 */ 93 static final int FIRST = 1; 94 95 // Implementation note: Keep these CATEGORY_* in sync with the category enum 96 // in attrs.xml 97 98 /** 99 * Category code for the order integer for items/groups that are part of a 100 * container -- or/add this with your base value. 101 */ 102 static final int CATEGORY_CONTAINER = 0x00010000; 103 104 /** 105 * Category code for the order integer for items/groups that are provided by 106 * the system -- or/add this with your base value. 107 */ 108 static final int CATEGORY_SYSTEM = 0x00020000; 109 110 /** 111 * Category code for the order integer for items/groups that are 112 * user-supplied secondary (infrequently used) options -- or/add this with 113 * your base value. 114 */ 115 static final int CATEGORY_SECONDARY = 0x00030000; 116 117 /** 118 * Category code for the order integer for items/groups that are 119 * alternative actions on the data that is currently displayed -- or/add 120 * this with your base value. 121 */ 122 static final int CATEGORY_ALTERNATIVE = 0x00040000; 123 124 /** 125 * Flag for {@link #addIntentOptions}: if set, do not automatically remove 126 * any existing menu items in the same group. 127 */ 128 static final int FLAG_APPEND_TO_GROUP = 0x0001; 129 130 /** 131 * Flag for {@link #performShortcut}: if set, do not close the menu after 132 * executing the shortcut. 133 */ 134 static final int FLAG_PERFORM_NO_CLOSE = 0x0001; 135 136 /** 137 * Flag for {@link #performShortcut(int, KeyEvent, int)}: if set, always 138 * close the menu after executing the shortcut. Closing the menu also resets 139 * the prepared state. 140 */ 141 static final int FLAG_ALWAYS_PERFORM_CLOSE = 0x0002; 142 143 /** 144 * Add a new item to the menu. This item displays the given title for its 145 * label. 146 * 147 * @param title The text to display for the item. 148 * @return The newly added menu item. 149 */ add(CharSequence title)150 public MenuItem add(CharSequence title); 151 152 /** 153 * Add a new item to the menu. This item displays the given title for its 154 * label. 155 * 156 * @param titleRes Resource identifier of title string. 157 * @return The newly added menu item. 158 */ add(@tringRes int titleRes)159 public MenuItem add(@StringRes int titleRes); 160 161 /** 162 * Add a new item to the menu. This item displays the given title for its 163 * label. 164 * 165 * @param groupId The group identifier that this item should be part of. 166 * This can be used to define groups of items for batch state 167 * changes. Normally use {@link #NONE} if an item should not be in a 168 * group. 169 * @param itemId Unique item ID. Use {@link #NONE} if you do not need a 170 * unique ID. 171 * @param order The order for the item. Use {@link #NONE} if you do not care 172 * about the order. See {@link MenuItem#getOrder()}. 173 * @param title The text to display for the item. 174 * @return The newly added menu item. 175 */ add(int groupId, int itemId, int order, CharSequence title)176 public MenuItem add(int groupId, int itemId, int order, CharSequence title); 177 178 /** 179 * Variation on {@link #add(int, int, int, CharSequence)} that takes a 180 * string resource identifier instead of the string itself. 181 * 182 * @param groupId The group identifier that this item should be part of. 183 * This can also be used to define groups of items for batch state 184 * changes. Normally use {@link #NONE} if an item should not be in a 185 * group. 186 * @param itemId Unique item ID. Use {@link #NONE} if you do not need a 187 * unique ID. 188 * @param order The order for the item. Use {@link #NONE} if you do not care 189 * about the order. See {@link MenuItem#getOrder()}. 190 * @param titleRes Resource identifier of title string. 191 * @return The newly added menu item. 192 */ add(int groupId, int itemId, int order, @StringRes int titleRes)193 public MenuItem add(int groupId, int itemId, int order, @StringRes int titleRes); 194 195 /** 196 * Add a new sub-menu to the menu. This item displays the given title for 197 * its label. To modify other attributes on the submenu's menu item, use 198 * {@link SubMenu#getItem()}. 199 * 200 * @param title The text to display for the item. 201 * @return The newly added sub-menu 202 */ addSubMenu(final CharSequence title)203 SubMenu addSubMenu(final CharSequence title); 204 205 /** 206 * Add a new sub-menu to the menu. This item displays the given title for 207 * its label. To modify other attributes on the submenu's menu item, use 208 * {@link SubMenu#getItem()}. 209 * 210 * @param titleRes Resource identifier of title string. 211 * @return The newly added sub-menu 212 */ addSubMenu(@tringRes final int titleRes)213 SubMenu addSubMenu(@StringRes final int titleRes); 214 215 /** 216 * Add a new sub-menu to the menu. This item displays the given 217 * <var>title</var> for its label. To modify other attributes on the 218 * submenu's menu item, use {@link SubMenu#getItem()}. 219 *<p> 220 * Note that you can only have one level of sub-menus, i.e. you cannnot add 221 * a subMenu to a subMenu: An {@link UnsupportedOperationException} will be 222 * thrown if you try. 223 * 224 * @param groupId The group identifier that this item should be part of. 225 * This can also be used to define groups of items for batch state 226 * changes. Normally use {@link #NONE} if an item should not be in a 227 * group. 228 * @param itemId Unique item ID. Use {@link #NONE} if you do not need a 229 * unique ID. 230 * @param order The order for the item. Use {@link #NONE} if you do not care 231 * about the order. See {@link MenuItem#getOrder()}. 232 * @param title The text to display for the item. 233 * @return The newly added sub-menu 234 */ addSubMenu(final int groupId, final int itemId, int order, final CharSequence title)235 SubMenu addSubMenu(final int groupId, final int itemId, int order, final CharSequence title); 236 237 /** 238 * Variation on {@link #addSubMenu(int, int, int, CharSequence)} that takes 239 * a string resource identifier for the title instead of the string itself. 240 * 241 * @param groupId The group identifier that this item should be part of. 242 * This can also be used to define groups of items for batch state 243 * changes. Normally use {@link #NONE} if an item should not be in a group. 244 * @param itemId Unique item ID. Use {@link #NONE} if you do not need a unique ID. 245 * @param order The order for the item. Use {@link #NONE} if you do not care about the 246 * order. See {@link MenuItem#getOrder()}. 247 * @param titleRes Resource identifier of title string. 248 * @return The newly added sub-menu 249 */ addSubMenu(int groupId, int itemId, int order, @StringRes int titleRes)250 SubMenu addSubMenu(int groupId, int itemId, int order, @StringRes int titleRes); 251 252 /** 253 * Add a group of menu items corresponding to actions that can be performed 254 * for a particular Intent. The Intent is most often configured with a null 255 * action, the data that the current activity is working with, and includes 256 * either the {@link Intent#CATEGORY_ALTERNATIVE} or 257 * {@link Intent#CATEGORY_SELECTED_ALTERNATIVE} to find activities that have 258 * said they would like to be included as optional action. You can, however, 259 * use any Intent you want. 260 * 261 * <p> 262 * See {@link android.content.pm.PackageManager#queryIntentActivityOptions} 263 * for more * details on the <var>caller</var>, <var>specifics</var>, and 264 * <var>intent</var> arguments. The list returned by that function is used 265 * to populate the resulting menu items. 266 * 267 * <p> 268 * All of the menu items of possible options for the intent will be added 269 * with the given group and id. You can use the group to control ordering of 270 * the items in relation to other items in the menu. Normally this function 271 * will automatically remove any existing items in the menu in the same 272 * group and place a divider above and below the added items; this behavior 273 * can be modified with the <var>flags</var> parameter. For each of the 274 * generated items {@link MenuItem#setIntent} is called to associate the 275 * appropriate Intent with the item; this means the activity will 276 * automatically be started for you without having to do anything else. 277 * 278 * @param groupId The group identifier that the items should be part of. 279 * This can also be used to define groups of items for batch state 280 * changes. Normally use {@link #NONE} if the items should not be in 281 * a group. 282 * @param itemId Unique item ID. Use {@link #NONE} if you do not need a 283 * unique ID. 284 * @param order The order for the items. Use {@link #NONE} if you do not 285 * care about the order. See {@link MenuItem#getOrder()}. 286 * @param caller The current activity component name as defined by 287 * queryIntentActivityOptions(). 288 * @param specifics Specific items to place first as defined by 289 * queryIntentActivityOptions(). 290 * @param intent Intent describing the kinds of items to populate in the 291 * list as defined by queryIntentActivityOptions(). 292 * @param flags Additional options controlling how the items are added. 293 * @param outSpecificItems Optional array in which to place the menu items 294 * that were generated for each of the <var>specifics</var> that were 295 * requested. Entries may be null if no activity was found for that 296 * specific action. 297 * @return The number of menu items that were added. 298 * 299 * @see #FLAG_APPEND_TO_GROUP 300 * @see MenuItem#setIntent 301 * @see android.content.pm.PackageManager#queryIntentActivityOptions 302 */ addIntentOptions(int groupId, int itemId, int order, ComponentName caller, Intent[] specifics, Intent intent, int flags, MenuItem[] outSpecificItems)303 public int addIntentOptions(int groupId, int itemId, int order, 304 ComponentName caller, Intent[] specifics, 305 Intent intent, int flags, MenuItem[] outSpecificItems); 306 307 /** 308 * Remove the item with the given identifier. 309 * 310 * @param id The item to be removed. If there is no item with this 311 * identifier, nothing happens. 312 */ removeItem(int id)313 public void removeItem(int id); 314 315 /** 316 * Remove all items in the given group. 317 * 318 * @param groupId The group to be removed. If there are no items in this 319 * group, nothing happens. 320 */ removeGroup(int groupId)321 public void removeGroup(int groupId); 322 323 /** 324 * Remove all existing items from the menu, leaving it empty as if it had 325 * just been created. 326 */ clear()327 public void clear(); 328 329 /** 330 * Control whether a particular group of items can show a check mark. This 331 * is similar to calling {@link MenuItem#setCheckable} on all of the menu items 332 * with the given group identifier, but in addition you can control whether 333 * this group contains a mutually-exclusive set items. This should be called 334 * after the items of the group have been added to the menu. 335 * 336 * @param group The group of items to operate on. 337 * @param checkable Set to true to allow a check mark, false to 338 * disallow. The default is false. 339 * @param exclusive If set to true, only one item in this group can be 340 * checked at a time; checking an item will automatically 341 * uncheck all others in the group. If set to false, each 342 * item can be checked independently of the others. 343 * 344 * @see MenuItem#setCheckable 345 * @see MenuItem#setChecked 346 */ setGroupCheckable(int group, boolean checkable, boolean exclusive)347 public void setGroupCheckable(int group, boolean checkable, boolean exclusive); 348 349 /** 350 * Show or hide all menu items that are in the given group. 351 * 352 * @param group The group of items to operate on. 353 * @param visible If true the items are visible, else they are hidden. 354 * 355 * @see MenuItem#setVisible 356 */ setGroupVisible(int group, boolean visible)357 public void setGroupVisible(int group, boolean visible); 358 359 /** 360 * Enable or disable all menu items that are in the given group. 361 * 362 * @param group The group of items to operate on. 363 * @param enabled If true the items will be enabled, else they will be disabled. 364 * 365 * @see MenuItem#setEnabled 366 */ setGroupEnabled(int group, boolean enabled)367 public void setGroupEnabled(int group, boolean enabled); 368 369 /** 370 * Return whether the menu currently has item items that are visible. 371 * 372 * @return True if there is one or more item visible, 373 * else false. 374 */ hasVisibleItems()375 public boolean hasVisibleItems(); 376 377 /** 378 * Return the menu item with a particular identifier. 379 * 380 * @param id The identifier to find. 381 * 382 * @return The menu item object, or null if there is no item with 383 * this identifier. 384 */ findItem(int id)385 public MenuItem findItem(int id); 386 387 /** 388 * Get the number of items in the menu. Note that this will change any 389 * times items are added or removed from the menu. 390 * 391 * @return The item count. 392 */ size()393 public int size(); 394 395 /** 396 * Gets the menu item at the given index. 397 * 398 * @param index The index of the menu item to return. 399 * @return The menu item. 400 * @exception IndexOutOfBoundsException 401 * when {@code index < 0 || >= size()} 402 */ getItem(int index)403 public MenuItem getItem(int index); 404 405 /** 406 * Closes the menu, if open. 407 */ close()408 public void close(); 409 410 /** 411 * Execute the menu item action associated with the given shortcut 412 * character. 413 * 414 * @param keyCode The keycode of the shortcut key. 415 * @param event Key event message. 416 * @param flags Additional option flags or 0. 417 * 418 * @return If the given shortcut exists and is shown, returns 419 * true; else returns false. 420 * 421 * @see #FLAG_PERFORM_NO_CLOSE 422 */ performShortcut(int keyCode, KeyEvent event, int flags)423 public boolean performShortcut(int keyCode, KeyEvent event, int flags); 424 425 /** 426 * Is a keypress one of the defined shortcut keys for this window. 427 * @param keyCode the key code from {@link KeyEvent} to check. 428 * @param event the {@link KeyEvent} to use to help check. 429 */ isShortcutKey(int keyCode, KeyEvent event)430 boolean isShortcutKey(int keyCode, KeyEvent event); 431 432 /** 433 * Execute the menu item action associated with the given menu identifier. 434 * 435 * @param id Identifier associated with the menu item. 436 * @param flags Additional option flags or 0. 437 * 438 * @return If the given identifier exists and is shown, returns 439 * true; else returns false. 440 * 441 * @see #FLAG_PERFORM_NO_CLOSE 442 */ performIdentifierAction(int id, int flags)443 public boolean performIdentifierAction(int id, int flags); 444 445 446 /** 447 * Control whether the menu should be running in qwerty mode (alphabetic 448 * shortcuts) or 12-key mode (numeric shortcuts). 449 * 450 * @param isQwerty If true the menu will use alphabetic shortcuts; else it 451 * will use numeric shortcuts. 452 */ setQwertyMode(boolean isQwerty)453 public void setQwertyMode(boolean isQwerty); 454 455 /** 456 * Enable or disable the group dividers. 457 */ setGroupDividerEnabled(boolean groupDividerEnabled)458 default void setGroupDividerEnabled(boolean groupDividerEnabled) { 459 } 460 }