MenuItem.java revision ec66a3a9e06ae91e0b49a5e858e46fe0c91606f1
1/* 2 * Copyright (C) 2008 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.Intent; 21import android.graphics.drawable.Drawable; 22import android.view.ContextMenu.ContextMenuInfo; 23import android.view.View.OnCreateContextMenuListener; 24 25/** 26 * Interface for direct access to a previously created menu item. 27 * <p> 28 * An Item is returned by calling one of the {@link android.view.Menu#add} 29 * methods. 30 * <p> 31 * For a feature set of specific menu types, see {@link Menu}. 32 */ 33public interface MenuItem { 34 /* 35 * These should be kept in sync with attrs.xml enum constants for showAsAction 36 */ 37 /** Never show this item as a button in an Action Bar. */ 38 public static final int SHOW_AS_ACTION_NEVER = 0; 39 /** Show this item as a button in an Action Bar if the system decides there is room for it. */ 40 public static final int SHOW_AS_ACTION_IF_ROOM = 1; 41 /** 42 * Always show this item as a button in an Action Bar. 43 * Use sparingly! If too many items are set to always show in the Action Bar it can 44 * crowd the Action Bar and degrade the user experience on devices with smaller screens. 45 * A good rule of thumb is to have no more than 2 items set to always show at a time. 46 */ 47 public static final int SHOW_AS_ACTION_ALWAYS = 2; 48 49 /** 50 * Interface definition for a callback to be invoked when a menu item is 51 * clicked. 52 * 53 * @see Activity#onContextItemSelected(MenuItem) 54 * @see Activity#onOptionsItemSelected(MenuItem) 55 */ 56 public interface OnMenuItemClickListener { 57 /** 58 * Called when a menu item has been invoked. This is the first code 59 * that is executed; if it returns true, no other callbacks will be 60 * executed. 61 * 62 * @param item The menu item that was invoked. 63 * 64 * @return Return true to consume this click and prevent others from 65 * executing. 66 */ 67 public boolean onMenuItemClick(MenuItem item); 68 } 69 70 /** 71 * Return the identifier for this menu item. The identifier can not 72 * be changed after the menu is created. 73 * 74 * @return The menu item's identifier. 75 */ 76 public int getItemId(); 77 78 /** 79 * Return the group identifier that this menu item is part of. The group 80 * identifier can not be changed after the menu is created. 81 * 82 * @return The menu item's group identifier. 83 */ 84 public int getGroupId(); 85 86 /** 87 * Return the category and order within the category of this item. This 88 * item will be shown before all items (within its category) that have 89 * order greater than this value. 90 * <p> 91 * An order integer contains the item's category (the upper bits of the 92 * integer; set by or/add the category with the order within the 93 * category) and the ordering of the item within that category (the 94 * lower bits). Example categories are {@link Menu#CATEGORY_SYSTEM}, 95 * {@link Menu#CATEGORY_SECONDARY}, {@link Menu#CATEGORY_ALTERNATIVE}, 96 * {@link Menu#CATEGORY_CONTAINER}. See {@link Menu} for a full list. 97 * 98 * @return The order of this item. 99 */ 100 public int getOrder(); 101 102 /** 103 * Change the title associated with this item. 104 * 105 * @param title The new text to be displayed. 106 * @return This Item so additional setters can be called. 107 */ 108 public MenuItem setTitle(CharSequence title); 109 110 /** 111 * Change the title associated with this item. 112 * <p> 113 * Some menu types do not sufficient space to show the full title, and 114 * instead a condensed title is preferred. See {@link Menu} for more 115 * information. 116 * 117 * @param title The resource id of the new text to be displayed. 118 * @return This Item so additional setters can be called. 119 * @see #setTitleCondensed(CharSequence) 120 */ 121 122 public MenuItem setTitle(int title); 123 124 /** 125 * Retrieve the current title of the item. 126 * 127 * @return The title. 128 */ 129 public CharSequence getTitle(); 130 131 /** 132 * Change the condensed title associated with this item. The condensed 133 * title is used in situations where the normal title may be too long to 134 * be displayed. 135 * 136 * @param title The new text to be displayed as the condensed title. 137 * @return This Item so additional setters can be called. 138 */ 139 public MenuItem setTitleCondensed(CharSequence title); 140 141 /** 142 * Retrieve the current condensed title of the item. If a condensed 143 * title was never set, it will return the normal title. 144 * 145 * @return The condensed title, if it exists. 146 * Otherwise the normal title. 147 */ 148 public CharSequence getTitleCondensed(); 149 150 /** 151 * Change the icon associated with this item. This icon will not always be 152 * shown, so the title should be sufficient in describing this item. See 153 * {@link Menu} for the menu types that support icons. 154 * 155 * @param icon The new icon (as a Drawable) to be displayed. 156 * @return This Item so additional setters can be called. 157 */ 158 public MenuItem setIcon(Drawable icon); 159 160 /** 161 * Change the icon associated with this item. This icon will not always be 162 * shown, so the title should be sufficient in describing this item. See 163 * {@link Menu} for the menu types that support icons. 164 * <p> 165 * This method will set the resource ID of the icon which will be used to 166 * lazily get the Drawable when this item is being shown. 167 * 168 * @param iconRes The new icon (as a resource ID) to be displayed. 169 * @return This Item so additional setters can be called. 170 */ 171 public MenuItem setIcon(int iconRes); 172 173 /** 174 * Returns the icon for this item as a Drawable (getting it from resources if it hasn't been 175 * loaded before). 176 * 177 * @return The icon as a Drawable. 178 */ 179 public Drawable getIcon(); 180 181 /** 182 * Change the Intent associated with this item. By default there is no 183 * Intent associated with a menu item. If you set one, and nothing 184 * else handles the item, then the default behavior will be to call 185 * {@link android.content.Context#startActivity} with the given Intent. 186 * 187 * <p>Note that setIntent() can not be used with the versions of 188 * {@link Menu#add} that take a Runnable, because {@link Runnable#run} 189 * does not return a value so there is no way to tell if it handled the 190 * item. In this case it is assumed that the Runnable always handles 191 * the item, and the intent will never be started. 192 * 193 * @see #getIntent 194 * @param intent The Intent to associated with the item. This Intent 195 * object is <em>not</em> copied, so be careful not to 196 * modify it later. 197 * @return This Item so additional setters can be called. 198 */ 199 public MenuItem setIntent(Intent intent); 200 201 /** 202 * Return the Intent associated with this item. This returns a 203 * reference to the Intent which you can change as desired to modify 204 * what the Item is holding. 205 * 206 * @see #setIntent 207 * @return Returns the last value supplied to {@link #setIntent}, or 208 * null. 209 */ 210 public Intent getIntent(); 211 212 /** 213 * Change both the numeric and alphabetic shortcut associated with this 214 * item. Note that the shortcut will be triggered when the key that 215 * generates the given character is pressed alone or along with with the alt 216 * key. Also note that case is not significant and that alphabetic shortcut 217 * characters will be displayed in lower case. 218 * <p> 219 * See {@link Menu} for the menu types that support shortcuts. 220 * 221 * @param numericChar The numeric shortcut key. This is the shortcut when 222 * using a numeric (e.g., 12-key) keyboard. 223 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 224 * using a keyboard with alphabetic keys. 225 * @return This Item so additional setters can be called. 226 */ 227 public MenuItem setShortcut(char numericChar, char alphaChar); 228 229 /** 230 * Change the numeric shortcut associated with this item. 231 * <p> 232 * See {@link Menu} for the menu types that support shortcuts. 233 * 234 * @param numericChar The numeric shortcut key. This is the shortcut when 235 * using a 12-key (numeric) keyboard. 236 * @return This Item so additional setters can be called. 237 */ 238 public MenuItem setNumericShortcut(char numericChar); 239 240 /** 241 * Return the char for this menu item's numeric (12-key) shortcut. 242 * 243 * @return Numeric character to use as a shortcut. 244 */ 245 public char getNumericShortcut(); 246 247 /** 248 * Change the alphabetic shortcut associated with this item. The shortcut 249 * will be triggered when the key that generates the given character is 250 * pressed alone or along with with the alt key. Case is not significant and 251 * shortcut characters will be displayed in lower case. Note that menu items 252 * with the characters '\b' or '\n' as shortcuts will get triggered by the 253 * Delete key or Carriage Return key, respectively. 254 * <p> 255 * See {@link Menu} for the menu types that support shortcuts. 256 * 257 * @param alphaChar The alphabetic shortcut key. This is the shortcut when 258 * using a keyboard with alphabetic keys. 259 * @return This Item so additional setters can be called. 260 */ 261 public MenuItem setAlphabeticShortcut(char alphaChar); 262 263 /** 264 * Return the char for this menu item's alphabetic shortcut. 265 * 266 * @return Alphabetic character to use as a shortcut. 267 */ 268 public char getAlphabeticShortcut(); 269 270 /** 271 * Control whether this item can display a check mark. Setting this does 272 * not actually display a check mark (see {@link #setChecked} for that); 273 * rather, it ensures there is room in the item in which to display a 274 * check mark. 275 * <p> 276 * See {@link Menu} for the menu types that support check marks. 277 * 278 * @param checkable Set to true to allow a check mark, false to 279 * disallow. The default is false. 280 * @see #setChecked 281 * @see #isCheckable 282 * @see Menu#setGroupCheckable 283 * @return This Item so additional setters can be called. 284 */ 285 public MenuItem setCheckable(boolean checkable); 286 287 /** 288 * Return whether the item can currently display a check mark. 289 * 290 * @return If a check mark can be displayed, returns true. 291 * 292 * @see #setCheckable 293 */ 294 public boolean isCheckable(); 295 296 /** 297 * Control whether this item is shown with a check mark. Note that you 298 * must first have enabled checking with {@link #setCheckable} or else 299 * the check mark will not appear. If this item is a member of a group that contains 300 * mutually-exclusive items (set via {@link Menu#setGroupCheckable(int, boolean, boolean)}, 301 * the other items in the group will be unchecked. 302 * <p> 303 * See {@link Menu} for the menu types that support check marks. 304 * 305 * @see #setCheckable 306 * @see #isChecked 307 * @see Menu#setGroupCheckable 308 * @param checked Set to true to display a check mark, false to hide 309 * it. The default value is false. 310 * @return This Item so additional setters can be called. 311 */ 312 public MenuItem setChecked(boolean checked); 313 314 /** 315 * Return whether the item is currently displaying a check mark. 316 * 317 * @return If a check mark is displayed, returns true. 318 * 319 * @see #setChecked 320 */ 321 public boolean isChecked(); 322 323 /** 324 * Sets the visibility of the menu item. Even if a menu item is not visible, 325 * it may still be invoked via its shortcut (to completely disable an item, 326 * set it to invisible and {@link #setEnabled(boolean) disabled}). 327 * 328 * @param visible If true then the item will be visible; if false it is 329 * hidden. 330 * @return This Item so additional setters can be called. 331 */ 332 public MenuItem setVisible(boolean visible); 333 334 /** 335 * Return the visibility of the menu item. 336 * 337 * @return If true the item is visible; else it is hidden. 338 */ 339 public boolean isVisible(); 340 341 /** 342 * Sets whether the menu item is enabled. Disabling a menu item will not 343 * allow it to be invoked via its shortcut. The menu item will still be 344 * visible. 345 * 346 * @param enabled If true then the item will be invokable; if false it is 347 * won't be invokable. 348 * @return This Item so additional setters can be called. 349 */ 350 public MenuItem setEnabled(boolean enabled); 351 352 /** 353 * Return the enabled state of the menu item. 354 * 355 * @return If true the item is enabled and hence invokable; else it is not. 356 */ 357 public boolean isEnabled(); 358 359 /** 360 * Check whether this item has an associated sub-menu. I.e. it is a 361 * sub-menu of another menu. 362 * 363 * @return If true this item has a menu; else it is a 364 * normal item. 365 */ 366 public boolean hasSubMenu(); 367 368 /** 369 * Get the sub-menu to be invoked when this item is selected, if it has 370 * one. See {@link #hasSubMenu()}. 371 * 372 * @return The associated menu if there is one, else null 373 */ 374 public SubMenu getSubMenu(); 375 376 /** 377 * Set a custom listener for invocation of this menu item. In most 378 * situations, it is more efficient and easier to use 379 * {@link Activity#onOptionsItemSelected(MenuItem)} or 380 * {@link Activity#onContextItemSelected(MenuItem)}. 381 * 382 * @param menuItemClickListener The object to receive invokations. 383 * @return This Item so additional setters can be called. 384 * @see Activity#onOptionsItemSelected(MenuItem) 385 * @see Activity#onContextItemSelected(MenuItem) 386 */ 387 public MenuItem setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener); 388 389 /** 390 * Gets the extra information linked to this menu item. This extra 391 * information is set by the View that added this menu item to the 392 * menu. 393 * 394 * @see OnCreateContextMenuListener 395 * @return The extra information linked to the View that added this 396 * menu item to the menu. This can be null. 397 */ 398 public ContextMenuInfo getMenuInfo(); 399 400 /** 401 * Sets how this item should display in the presence of an Action Bar. 402 * 403 * @param actionEnum How the item should display. One of 404 * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or 405 * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default. 406 * 407 * @see android.app.ActionBar 408 */ 409 public void setShowAsAction(int actionEnum); 410}