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