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