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