The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | |
| 17 | package android.view; |
| 18 | |
Tor Norbye | 7b9c912 | 2013-05-30 16:48:33 -0700 | [diff] [blame] | 19 | import android.annotation.DrawableRes; |
| 20 | import android.annotation.LayoutRes; |
Kirill Grouchnikov | 6eea0d2 | 2017-03-21 13:52:09 -0400 | [diff] [blame] | 21 | import android.annotation.Nullable; |
Tor Norbye | 7b9c912 | 2013-05-30 16:48:33 -0700 | [diff] [blame] | 22 | import android.annotation.StringRes; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 23 | import android.app.Activity; |
| 24 | import android.content.Intent; |
Kirill Grouchnikov | 6eea0d2 | 2017-03-21 13:52:09 -0400 | [diff] [blame] | 25 | import android.content.res.ColorStateList; |
| 26 | import android.graphics.PorterDuff; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 27 | import android.graphics.drawable.Drawable; |
| 28 | import android.view.ContextMenu.ContextMenuInfo; |
| 29 | import android.view.View.OnCreateContextMenuListener; |
| 30 | |
| 31 | /** |
| 32 | * Interface for direct access to a previously created menu item. |
| 33 | * <p> |
| 34 | * An Item is returned by calling one of the {@link android.view.Menu#add} |
| 35 | * methods. |
| 36 | * <p> |
| 37 | * For a feature set of specific menu types, see {@link Menu}. |
Joe Fernandez | 558459f | 2011-10-13 16:47:36 -0700 | [diff] [blame] | 38 | * |
| 39 | * <div class="special reference"> |
| 40 | * <h3>Developer Guides</h3> |
| 41 | * <p>For information about creating menus, read the |
| 42 | * <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide.</p> |
| 43 | * </div> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 44 | */ |
| 45 | public interface MenuItem { |
Adam Powell | 89e0645 | 2010-06-23 20:24:52 -0700 | [diff] [blame] | 46 | /* |
| 47 | * These should be kept in sync with attrs.xml enum constants for showAsAction |
| 48 | */ |
| 49 | /** Never show this item as a button in an Action Bar. */ |
| 50 | public static final int SHOW_AS_ACTION_NEVER = 0; |
| 51 | /** Show this item as a button in an Action Bar if the system decides there is room for it. */ |
| 52 | public static final int SHOW_AS_ACTION_IF_ROOM = 1; |
| 53 | /** |
| 54 | * Always show this item as a button in an Action Bar. |
| 55 | * Use sparingly! If too many items are set to always show in the Action Bar it can |
| 56 | * crowd the Action Bar and degrade the user experience on devices with smaller screens. |
| 57 | * A good rule of thumb is to have no more than 2 items set to always show at a time. |
| 58 | */ |
| 59 | public static final int SHOW_AS_ACTION_ALWAYS = 2; |
Adam Powell | d8404b2 | 2010-10-13 14:26:41 -0700 | [diff] [blame] | 60 | |
| 61 | /** |
| 62 | * When this item is in the action bar, always show it with a text label even if |
| 63 | * it also has an icon specified. |
| 64 | */ |
| 65 | public static final int SHOW_AS_ACTION_WITH_TEXT = 4; |
Adam Powell | 8d02dea | 2011-05-31 21:35:13 -0700 | [diff] [blame] | 66 | |
| 67 | /** |
| 68 | * This item's action view collapses to a normal menu item. |
| 69 | * When expanded, the action view temporarily takes over |
| 70 | * a larger segment of its container. |
| 71 | */ |
| 72 | public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8; |
Siyamed Sinir | 484c2e2 | 2017-06-07 16:26:19 -0700 | [diff] [blame] | 73 | |
| 74 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 75 | * Interface definition for a callback to be invoked when a menu item is |
| 76 | * clicked. |
| 77 | * |
| 78 | * @see Activity#onContextItemSelected(MenuItem) |
| 79 | * @see Activity#onOptionsItemSelected(MenuItem) |
| 80 | */ |
| 81 | public interface OnMenuItemClickListener { |
| 82 | /** |
| 83 | * Called when a menu item has been invoked. This is the first code |
| 84 | * that is executed; if it returns true, no other callbacks will be |
| 85 | * executed. |
| 86 | * |
| 87 | * @param item The menu item that was invoked. |
| 88 | * |
| 89 | * @return Return true to consume this click and prevent others from |
| 90 | * executing. |
| 91 | */ |
| 92 | public boolean onMenuItemClick(MenuItem item); |
| 93 | } |
| 94 | |
| 95 | /** |
Adam Powell | 8d02dea | 2011-05-31 21:35:13 -0700 | [diff] [blame] | 96 | * Interface definition for a callback to be invoked when a menu item |
| 97 | * marked with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} is |
| 98 | * expanded or collapsed. |
| 99 | * |
| 100 | * @see MenuItem#expandActionView() |
| 101 | * @see MenuItem#collapseActionView() |
| 102 | * @see MenuItem#setShowAsActionFlags(int) |
Adam Powell | 8d02dea | 2011-05-31 21:35:13 -0700 | [diff] [blame] | 103 | */ |
| 104 | public interface OnActionExpandListener { |
| 105 | /** |
| 106 | * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} |
| 107 | * is expanded. |
| 108 | * @param item Item that was expanded |
| 109 | * @return true if the item should expand, false if expansion should be suppressed. |
| 110 | */ |
| 111 | public boolean onMenuItemActionExpand(MenuItem item); |
| 112 | |
| 113 | /** |
| 114 | * Called when a menu item with {@link MenuItem#SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW} |
| 115 | * is collapsed. |
| 116 | * @param item Item that was collapsed |
| 117 | * @return true if the item should collapse, false if collapsing should be suppressed. |
| 118 | */ |
| 119 | public boolean onMenuItemActionCollapse(MenuItem item); |
| 120 | } |
| 121 | |
| 122 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 123 | * Return the identifier for this menu item. The identifier can not |
| 124 | * be changed after the menu is created. |
| 125 | * |
| 126 | * @return The menu item's identifier. |
| 127 | */ |
| 128 | public int getItemId(); |
| 129 | |
| 130 | /** |
| 131 | * Return the group identifier that this menu item is part of. The group |
| 132 | * identifier can not be changed after the menu is created. |
| 133 | * |
| 134 | * @return The menu item's group identifier. |
| 135 | */ |
| 136 | public int getGroupId(); |
| 137 | |
| 138 | /** |
| 139 | * Return the category and order within the category of this item. This |
| 140 | * item will be shown before all items (within its category) that have |
| 141 | * order greater than this value. |
| 142 | * <p> |
| 143 | * An order integer contains the item's category (the upper bits of the |
| 144 | * integer; set by or/add the category with the order within the |
| 145 | * category) and the ordering of the item within that category (the |
| 146 | * lower bits). Example categories are {@link Menu#CATEGORY_SYSTEM}, |
| 147 | * {@link Menu#CATEGORY_SECONDARY}, {@link Menu#CATEGORY_ALTERNATIVE}, |
| 148 | * {@link Menu#CATEGORY_CONTAINER}. See {@link Menu} for a full list. |
| 149 | * |
| 150 | * @return The order of this item. |
| 151 | */ |
| 152 | public int getOrder(); |
| 153 | |
| 154 | /** |
| 155 | * Change the title associated with this item. |
| 156 | * |
| 157 | * @param title The new text to be displayed. |
| 158 | * @return This Item so additional setters can be called. |
| 159 | */ |
| 160 | public MenuItem setTitle(CharSequence title); |
| 161 | |
| 162 | /** |
| 163 | * Change the title associated with this item. |
| 164 | * <p> |
| 165 | * Some menu types do not sufficient space to show the full title, and |
| 166 | * instead a condensed title is preferred. See {@link Menu} for more |
| 167 | * information. |
| 168 | * |
| 169 | * @param title The resource id of the new text to be displayed. |
| 170 | * @return This Item so additional setters can be called. |
| 171 | * @see #setTitleCondensed(CharSequence) |
| 172 | */ |
| 173 | |
Tor Norbye | 7b9c912 | 2013-05-30 16:48:33 -0700 | [diff] [blame] | 174 | public MenuItem setTitle(@StringRes int title); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 175 | |
| 176 | /** |
| 177 | * Retrieve the current title of the item. |
| 178 | * |
| 179 | * @return The title. |
| 180 | */ |
| 181 | public CharSequence getTitle(); |
| 182 | |
| 183 | /** |
| 184 | * Change the condensed title associated with this item. The condensed |
| 185 | * title is used in situations where the normal title may be too long to |
| 186 | * be displayed. |
| 187 | * |
| 188 | * @param title The new text to be displayed as the condensed title. |
| 189 | * @return This Item so additional setters can be called. |
| 190 | */ |
| 191 | public MenuItem setTitleCondensed(CharSequence title); |
| 192 | |
| 193 | /** |
| 194 | * Retrieve the current condensed title of the item. If a condensed |
| 195 | * title was never set, it will return the normal title. |
| 196 | * |
| 197 | * @return The condensed title, if it exists. |
| 198 | * Otherwise the normal title. |
| 199 | */ |
| 200 | public CharSequence getTitleCondensed(); |
| 201 | |
| 202 | /** |
| 203 | * Change the icon associated with this item. This icon will not always be |
| 204 | * shown, so the title should be sufficient in describing this item. See |
| 205 | * {@link Menu} for the menu types that support icons. |
| 206 | * |
| 207 | * @param icon The new icon (as a Drawable) to be displayed. |
| 208 | * @return This Item so additional setters can be called. |
| 209 | */ |
| 210 | public MenuItem setIcon(Drawable icon); |
| 211 | |
| 212 | /** |
| 213 | * Change the icon associated with this item. This icon will not always be |
| 214 | * shown, so the title should be sufficient in describing this item. See |
| 215 | * {@link Menu} for the menu types that support icons. |
| 216 | * <p> |
| 217 | * This method will set the resource ID of the icon which will be used to |
| 218 | * lazily get the Drawable when this item is being shown. |
| 219 | * |
| 220 | * @param iconRes The new icon (as a resource ID) to be displayed. |
| 221 | * @return This Item so additional setters can be called. |
| 222 | */ |
Tor Norbye | 7b9c912 | 2013-05-30 16:48:33 -0700 | [diff] [blame] | 223 | public MenuItem setIcon(@DrawableRes int iconRes); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 224 | |
| 225 | /** |
| 226 | * Returns the icon for this item as a Drawable (getting it from resources if it hasn't been |
Kirill Grouchnikov | 6eea0d2 | 2017-03-21 13:52:09 -0400 | [diff] [blame] | 227 | * loaded before). Note that if you call {@link #setIconTintList(ColorStateList)} or |
| 228 | * {@link #setIconTintMode(PorterDuff.Mode)} on this item, and you use a custom menu presenter |
| 229 | * in your application, you have to apply the tinting explicitly on the {@link Drawable} |
| 230 | * returned by this method. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 231 | * |
| 232 | * @return The icon as a Drawable. |
| 233 | */ |
| 234 | public Drawable getIcon(); |
Kirill Grouchnikov | 6eea0d2 | 2017-03-21 13:52:09 -0400 | [diff] [blame] | 235 | |
| 236 | /** |
| 237 | * Applies a tint to this item's icon. Does not modify the |
| 238 | * current tint mode, which is {@link PorterDuff.Mode#SRC_IN} by default. |
| 239 | * <p> |
| 240 | * Subsequent calls to {@link #setIcon(Drawable)} or {@link #setIcon(int)} will |
| 241 | * automatically mutate the icon and apply the specified tint and |
| 242 | * tint mode using |
| 243 | * {@link Drawable#setTintList(ColorStateList)}. |
| 244 | * |
| 245 | * @param tint the tint to apply, may be {@code null} to clear tint |
| 246 | * |
| 247 | * @attr ref android.R.styleable#MenuItem_iconTint |
| 248 | * @see #getIconTintList() |
| 249 | * @see Drawable#setTintList(ColorStateList) |
| 250 | */ |
| 251 | public default MenuItem setIconTintList(@Nullable ColorStateList tint) { return this; } |
| 252 | |
| 253 | /** |
| 254 | * @return the tint applied to this item's icon |
| 255 | * @attr ref android.R.styleable#MenuItem_iconTint |
| 256 | * @see #setIconTintList(ColorStateList) |
| 257 | */ |
| 258 | @Nullable |
| 259 | public default ColorStateList getIconTintList() { return null; } |
| 260 | |
| 261 | /** |
| 262 | * Specifies the blending mode used to apply the tint specified by |
| 263 | * {@link #setIconTintList(ColorStateList)} to this item's icon. The default mode is |
| 264 | * {@link PorterDuff.Mode#SRC_IN}. |
| 265 | * |
| 266 | * @param tintMode the blending mode used to apply the tint, may be |
| 267 | * {@code null} to clear tint |
| 268 | * @attr ref android.R.styleable#MenuItem_iconTintMode |
| 269 | * @see #setIconTintList(ColorStateList) |
| 270 | * @see Drawable#setTintMode(PorterDuff.Mode) |
| 271 | */ |
| 272 | public default MenuItem setIconTintMode(@Nullable PorterDuff.Mode tintMode) { return this; } |
| 273 | |
| 274 | /** |
| 275 | * Returns the blending mode used to apply the tint to this item's icon, if specified. |
| 276 | * |
| 277 | * @return the blending mode used to apply the tint to this item's icon |
| 278 | * @attr ref android.R.styleable#MenuItem_iconTintMode |
| 279 | * @see #setIconTintMode(PorterDuff.Mode) |
| 280 | */ |
| 281 | @Nullable |
| 282 | public default PorterDuff.Mode getIconTintMode() { return null; } |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 283 | |
| 284 | /** |
| 285 | * Change the Intent associated with this item. By default there is no |
| 286 | * Intent associated with a menu item. If you set one, and nothing |
| 287 | * else handles the item, then the default behavior will be to call |
| 288 | * {@link android.content.Context#startActivity} with the given Intent. |
| 289 | * |
| 290 | * <p>Note that setIntent() can not be used with the versions of |
| 291 | * {@link Menu#add} that take a Runnable, because {@link Runnable#run} |
| 292 | * does not return a value so there is no way to tell if it handled the |
| 293 | * item. In this case it is assumed that the Runnable always handles |
| 294 | * the item, and the intent will never be started. |
| 295 | * |
| 296 | * @see #getIntent |
| 297 | * @param intent The Intent to associated with the item. This Intent |
| 298 | * object is <em>not</em> copied, so be careful not to |
| 299 | * modify it later. |
| 300 | * @return This Item so additional setters can be called. |
| 301 | */ |
| 302 | public MenuItem setIntent(Intent intent); |
| 303 | |
| 304 | /** |
| 305 | * Return the Intent associated with this item. This returns a |
| 306 | * reference to the Intent which you can change as desired to modify |
| 307 | * what the Item is holding. |
| 308 | * |
| 309 | * @see #setIntent |
| 310 | * @return Returns the last value supplied to {@link #setIntent}, or |
| 311 | * null. |
| 312 | */ |
| 313 | public Intent getIntent(); |
| 314 | |
| 315 | /** |
| 316 | * Change both the numeric and alphabetic shortcut associated with this |
| 317 | * item. Note that the shortcut will be triggered when the key that |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 318 | * generates the given character is pressed along with the corresponding |
| 319 | * modifier key. The default modifier is {@link KeyEvent#META_CTRL_ON} in |
| 320 | * case nothing is specified. Also note that case is not significant and |
| 321 | * that alphabetic shortcut characters will be handled in lower case. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 322 | * <p> |
| 323 | * See {@link Menu} for the menu types that support shortcuts. |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 324 | * |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 325 | * @param numericChar The numeric shortcut key. This is the shortcut when |
| 326 | * using a numeric (e.g., 12-key) keyboard. |
| 327 | * @param alphaChar The alphabetic shortcut key. This is the shortcut when |
| 328 | * using a keyboard with alphabetic keys. |
| 329 | * @return This Item so additional setters can be called. |
| 330 | */ |
| 331 | public MenuItem setShortcut(char numericChar, char alphaChar); |
| 332 | |
| 333 | /** |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 334 | * Change both the numeric and alphabetic shortcut associated with this |
| 335 | * item. Note that the shortcut will be triggered when the key that |
| 336 | * generates the given character is pressed along with the corresponding |
| 337 | * modifier key. Also note that case is not significant and that alphabetic |
| 338 | * shortcut characters will be handled in lower case. |
| 339 | * <p> |
| 340 | * See {@link Menu} for the menu types that support shortcuts. |
| 341 | * |
| 342 | * @param numericChar The numeric shortcut key. This is the shortcut when |
| 343 | * using a numeric (e.g., 12-key) keyboard. |
| 344 | * @param numericModifiers The numeric modifier associated with the shortcut. It should |
| 345 | * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, |
| 346 | * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, |
| 347 | * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. |
| 348 | * @param alphaChar The alphabetic shortcut key. This is the shortcut when |
| 349 | * using a keyboard with alphabetic keys. |
| 350 | * @param alphaModifiers The alphabetic modifier associated with the shortcut. It should |
| 351 | * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, |
| 352 | * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, |
| 353 | * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. |
| 354 | * @return This Item so additional setters can be called. |
| 355 | */ |
| 356 | default public MenuItem setShortcut(char numericChar, char alphaChar, int numericModifiers, |
| 357 | int alphaModifiers) { |
| 358 | if ((alphaModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON |
| 359 | && (numericModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON) { |
| 360 | return setShortcut(numericChar, alphaChar); |
| 361 | } else { |
| 362 | return this; |
| 363 | } |
| 364 | } |
| 365 | |
| 366 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 367 | * Change the numeric shortcut associated with this item. |
| 368 | * <p> |
| 369 | * See {@link Menu} for the menu types that support shortcuts. |
| 370 | * |
| 371 | * @param numericChar The numeric shortcut key. This is the shortcut when |
| 372 | * using a 12-key (numeric) keyboard. |
| 373 | * @return This Item so additional setters can be called. |
| 374 | */ |
| 375 | public MenuItem setNumericShortcut(char numericChar); |
| 376 | |
| 377 | /** |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 378 | * Change the numeric shortcut and modifiers associated with this item. |
| 379 | * <p> |
| 380 | * See {@link Menu} for the menu types that support shortcuts. |
| 381 | * |
| 382 | * @param numericChar The numeric shortcut key. This is the shortcut when |
| 383 | * using a 12-key (numeric) keyboard. |
| 384 | * @param numericModifiers The modifier associated with the shortcut. It should |
| 385 | * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, |
| 386 | * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, |
| 387 | * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. |
| 388 | * @return This Item so additional setters can be called. |
| 389 | */ |
| 390 | default public MenuItem setNumericShortcut(char numericChar, int numericModifiers) { |
| 391 | if ((numericModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON) { |
| 392 | return setNumericShortcut(numericChar); |
| 393 | } else { |
| 394 | return this; |
| 395 | } |
| 396 | } |
| 397 | |
| 398 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 399 | * Return the char for this menu item's numeric (12-key) shortcut. |
| 400 | * |
| 401 | * @return Numeric character to use as a shortcut. |
| 402 | */ |
| 403 | public char getNumericShortcut(); |
| 404 | |
| 405 | /** |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 406 | * Return the modifiers for this menu item's numeric (12-key) shortcut. |
| 407 | * The modifier is a combination of {@link KeyEvent#META_META_ON}, |
| 408 | * {@link KeyEvent#META_CTRL_ON}, {@link KeyEvent#META_ALT_ON}, |
| 409 | * {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_SYM_ON}, |
| 410 | * {@link KeyEvent#META_FUNCTION_ON}. |
| 411 | * For example, {@link KeyEvent#META_FUNCTION_ON}|{@link KeyEvent#META_CTRL_ON} |
| 412 | * |
| 413 | * @return Modifier associated with the numeric shortcut. |
| 414 | */ |
| 415 | default public int getNumericModifiers() { |
| 416 | return KeyEvent.META_CTRL_ON; |
| 417 | } |
| 418 | |
| 419 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 420 | * Change the alphabetic shortcut associated with this item. The shortcut |
| 421 | * will be triggered when the key that generates the given character is |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 422 | * pressed along with the corresponding modifier key. The default modifier |
| 423 | * is {@link KeyEvent#META_CTRL_ON} in case nothing is specified. Case is |
| 424 | * not significant and shortcut characters will be displayed in lower case. |
| 425 | * Note that menu items with the characters '\b' or '\n' as shortcuts will |
| 426 | * get triggered by the Delete key or Carriage Return key, respectively. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 427 | * <p> |
| 428 | * See {@link Menu} for the menu types that support shortcuts. |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 429 | * |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 430 | * @param alphaChar The alphabetic shortcut key. This is the shortcut when |
| 431 | * using a keyboard with alphabetic keys. |
| 432 | * @return This Item so additional setters can be called. |
| 433 | */ |
| 434 | public MenuItem setAlphabeticShortcut(char alphaChar); |
| 435 | |
| 436 | /** |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 437 | * Change the alphabetic shortcut associated with this item. The shortcut |
| 438 | * will be triggered when the key that generates the given character is |
| 439 | * pressed along with the modifier keys. Case is not significant and shortcut |
| 440 | * characters will be displayed in lower case. Note that menu items with |
| 441 | * the characters '\b' or '\n' as shortcuts will get triggered by the |
| 442 | * Delete key or Carriage Return key, respectively. |
| 443 | * <p> |
| 444 | * See {@link Menu} for the menu types that support shortcuts. |
| 445 | * |
| 446 | * @param alphaChar The alphabetic shortcut key. This is the shortcut when |
| 447 | * using a keyboard with alphabetic keys. |
| 448 | * @param alphaModifiers The modifier associated with the shortcut. It should |
| 449 | * be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON}, |
| 450 | * {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON}, |
| 451 | * {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}. |
| 452 | * @return This Item so additional setters can be called. |
| 453 | */ |
| 454 | default public MenuItem setAlphabeticShortcut(char alphaChar, int alphaModifiers) { |
| 455 | if ((alphaModifiers & Menu.SUPPORTED_MODIFIERS_MASK) == KeyEvent.META_CTRL_ON) { |
| 456 | return setAlphabeticShortcut(alphaChar); |
| 457 | } else { |
| 458 | return this; |
| 459 | } |
| 460 | } |
| 461 | |
| 462 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 463 | * Return the char for this menu item's alphabetic shortcut. |
| 464 | * |
| 465 | * @return Alphabetic character to use as a shortcut. |
| 466 | */ |
| 467 | public char getAlphabeticShortcut(); |
| 468 | |
| 469 | /** |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 470 | * Return the modifier for this menu item's alphabetic shortcut. |
| 471 | * The modifier is a combination of {@link KeyEvent#META_META_ON}, |
| 472 | * {@link KeyEvent#META_CTRL_ON}, {@link KeyEvent#META_ALT_ON}, |
| 473 | * {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_SYM_ON}, |
| 474 | * {@link KeyEvent#META_FUNCTION_ON}. |
| 475 | * For example, {@link KeyEvent#META_FUNCTION_ON}|{@link KeyEvent#META_CTRL_ON} |
| 476 | * |
| 477 | * @return Modifier associated with the keyboard shortcut. |
| 478 | */ |
| 479 | default public int getAlphabeticModifiers() { |
| 480 | return KeyEvent.META_CTRL_ON; |
| 481 | } |
| 482 | |
| 483 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 484 | * Control whether this item can display a check mark. Setting this does |
| 485 | * not actually display a check mark (see {@link #setChecked} for that); |
| 486 | * rather, it ensures there is room in the item in which to display a |
| 487 | * check mark. |
| 488 | * <p> |
| 489 | * See {@link Menu} for the menu types that support check marks. |
Peeyush Agarwal | e631e32 | 2016-10-19 11:41:42 +0100 | [diff] [blame] | 490 | * |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 491 | * @param checkable Set to true to allow a check mark, false to |
| 492 | * disallow. The default is false. |
| 493 | * @see #setChecked |
| 494 | * @see #isCheckable |
| 495 | * @see Menu#setGroupCheckable |
| 496 | * @return This Item so additional setters can be called. |
| 497 | */ |
| 498 | public MenuItem setCheckable(boolean checkable); |
| 499 | |
| 500 | /** |
| 501 | * Return whether the item can currently display a check mark. |
| 502 | * |
| 503 | * @return If a check mark can be displayed, returns true. |
| 504 | * |
| 505 | * @see #setCheckable |
| 506 | */ |
| 507 | public boolean isCheckable(); |
| 508 | |
| 509 | /** |
| 510 | * Control whether this item is shown with a check mark. Note that you |
| 511 | * must first have enabled checking with {@link #setCheckable} or else |
| 512 | * the check mark will not appear. If this item is a member of a group that contains |
| 513 | * mutually-exclusive items (set via {@link Menu#setGroupCheckable(int, boolean, boolean)}, |
| 514 | * the other items in the group will be unchecked. |
| 515 | * <p> |
| 516 | * See {@link Menu} for the menu types that support check marks. |
| 517 | * |
| 518 | * @see #setCheckable |
| 519 | * @see #isChecked |
| 520 | * @see Menu#setGroupCheckable |
| 521 | * @param checked Set to true to display a check mark, false to hide |
| 522 | * it. The default value is false. |
| 523 | * @return This Item so additional setters can be called. |
| 524 | */ |
| 525 | public MenuItem setChecked(boolean checked); |
| 526 | |
| 527 | /** |
| 528 | * Return whether the item is currently displaying a check mark. |
| 529 | * |
| 530 | * @return If a check mark is displayed, returns true. |
| 531 | * |
| 532 | * @see #setChecked |
| 533 | */ |
| 534 | public boolean isChecked(); |
| 535 | |
| 536 | /** |
| 537 | * Sets the visibility of the menu item. Even if a menu item is not visible, |
| 538 | * it may still be invoked via its shortcut (to completely disable an item, |
| 539 | * set it to invisible and {@link #setEnabled(boolean) disabled}). |
| 540 | * |
| 541 | * @param visible If true then the item will be visible; if false it is |
| 542 | * hidden. |
| 543 | * @return This Item so additional setters can be called. |
| 544 | */ |
| 545 | public MenuItem setVisible(boolean visible); |
| 546 | |
| 547 | /** |
| 548 | * Return the visibility of the menu item. |
| 549 | * |
| 550 | * @return If true the item is visible; else it is hidden. |
| 551 | */ |
| 552 | public boolean isVisible(); |
| 553 | |
| 554 | /** |
| 555 | * Sets whether the menu item is enabled. Disabling a menu item will not |
| 556 | * allow it to be invoked via its shortcut. The menu item will still be |
| 557 | * visible. |
| 558 | * |
| 559 | * @param enabled If true then the item will be invokable; if false it is |
| 560 | * won't be invokable. |
| 561 | * @return This Item so additional setters can be called. |
| 562 | */ |
| 563 | public MenuItem setEnabled(boolean enabled); |
| 564 | |
| 565 | /** |
| 566 | * Return the enabled state of the menu item. |
| 567 | * |
| 568 | * @return If true the item is enabled and hence invokable; else it is not. |
| 569 | */ |
| 570 | public boolean isEnabled(); |
| 571 | |
| 572 | /** |
| 573 | * Check whether this item has an associated sub-menu. I.e. it is a |
| 574 | * sub-menu of another menu. |
| 575 | * |
| 576 | * @return If true this item has a menu; else it is a |
| 577 | * normal item. |
| 578 | */ |
| 579 | public boolean hasSubMenu(); |
| 580 | |
| 581 | /** |
| 582 | * Get the sub-menu to be invoked when this item is selected, if it has |
| 583 | * one. See {@link #hasSubMenu()}. |
| 584 | * |
| 585 | * @return The associated menu if there is one, else null |
| 586 | */ |
| 587 | public SubMenu getSubMenu(); |
| 588 | |
| 589 | /** |
| 590 | * Set a custom listener for invocation of this menu item. In most |
| 591 | * situations, it is more efficient and easier to use |
| 592 | * {@link Activity#onOptionsItemSelected(MenuItem)} or |
| 593 | * {@link Activity#onContextItemSelected(MenuItem)}. |
| 594 | * |
| 595 | * @param menuItemClickListener The object to receive invokations. |
| 596 | * @return This Item so additional setters can be called. |
| 597 | * @see Activity#onOptionsItemSelected(MenuItem) |
| 598 | * @see Activity#onContextItemSelected(MenuItem) |
| 599 | */ |
| 600 | public MenuItem setOnMenuItemClickListener(MenuItem.OnMenuItemClickListener menuItemClickListener); |
| 601 | |
| 602 | /** |
| 603 | * Gets the extra information linked to this menu item. This extra |
| 604 | * information is set by the View that added this menu item to the |
| 605 | * menu. |
| 606 | * |
| 607 | * @see OnCreateContextMenuListener |
| 608 | * @return The extra information linked to the View that added this |
| 609 | * menu item to the menu. This can be null. |
| 610 | */ |
| 611 | public ContextMenuInfo getMenuInfo(); |
Adam Powell | 89e0645 | 2010-06-23 20:24:52 -0700 | [diff] [blame] | 612 | |
| 613 | /** |
| 614 | * Sets how this item should display in the presence of an Action Bar. |
Adam Powell | 759dc70 | 2010-11-15 15:12:20 -0800 | [diff] [blame] | 615 | * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, |
| 616 | * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should |
| 617 | * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. |
| 618 | * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, |
| 619 | * it should be shown with a text label. |
Adam Powell | 89e0645 | 2010-06-23 20:24:52 -0700 | [diff] [blame] | 620 | * |
| 621 | * @param actionEnum How the item should display. One of |
Adam Powell | ec66a3a | 2010-07-19 15:51:17 -0700 | [diff] [blame] | 622 | * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or |
| 623 | * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default. |
Adam Powell | 89e0645 | 2010-06-23 20:24:52 -0700 | [diff] [blame] | 624 | * |
| 625 | * @see android.app.ActionBar |
Adam Powell | cf78b3e | 2010-09-12 18:25:23 -0700 | [diff] [blame] | 626 | * @see #setActionView(View) |
Adam Powell | 89e0645 | 2010-06-23 20:24:52 -0700 | [diff] [blame] | 627 | */ |
| 628 | public void setShowAsAction(int actionEnum); |
Adam Powell | cf78b3e | 2010-09-12 18:25:23 -0700 | [diff] [blame] | 629 | |
| 630 | /** |
Adam Powell | 8d02dea | 2011-05-31 21:35:13 -0700 | [diff] [blame] | 631 | * Sets how this item should display in the presence of an Action Bar. |
| 632 | * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, |
| 633 | * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should |
| 634 | * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. |
| 635 | * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, |
| 636 | * it should be shown with a text label. |
| 637 | * |
| 638 | * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it |
| 639 | * returns the current MenuItem instance for call chaining. |
| 640 | * |
| 641 | * @param actionEnum How the item should display. One of |
| 642 | * {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or |
| 643 | * {@link #SHOW_AS_ACTION_NEVER}. SHOW_AS_ACTION_NEVER is the default. |
| 644 | * |
| 645 | * @see android.app.ActionBar |
| 646 | * @see #setActionView(View) |
| 647 | * @return This MenuItem instance for call chaining. |
| 648 | */ |
| 649 | public MenuItem setShowAsActionFlags(int actionEnum); |
| 650 | |
| 651 | /** |
Adam Powell | cf78b3e | 2010-09-12 18:25:23 -0700 | [diff] [blame] | 652 | * Set an action view for this menu item. An action view will be displayed in place |
| 653 | * of an automatically generated menu item element in the UI when this item is shown |
| 654 | * as an action within a parent. |
Svetoslav Ganov | 51ac0e9 | 2011-06-17 13:45:13 -0700 | [diff] [blame] | 655 | * <p> |
| 656 | * <strong>Note:</strong> Setting an action view overrides the action provider |
| 657 | * set via {@link #setActionProvider(ActionProvider)}. |
| 658 | * </p> |
Adam Powell | cf78b3e | 2010-09-12 18:25:23 -0700 | [diff] [blame] | 659 | * |
| 660 | * @param view View to use for presenting this item to the user. |
| 661 | * @return This Item so additional setters can be called. |
| 662 | * |
| 663 | * @see #setShowAsAction(int) |
| 664 | */ |
| 665 | public MenuItem setActionView(View view); |
| 666 | |
| 667 | /** |
Adam Powell | 3f476b3 | 2011-01-03 19:25:36 -0800 | [diff] [blame] | 668 | * Set an action view for this menu item. An action view will be displayed in place |
| 669 | * of an automatically generated menu item element in the UI when this item is shown |
| 670 | * as an action within a parent. |
Svetoslav Ganov | 51ac0e9 | 2011-06-17 13:45:13 -0700 | [diff] [blame] | 671 | * <p> |
| 672 | * <strong>Note:</strong> Setting an action view overrides the action provider |
| 673 | * set via {@link #setActionProvider(ActionProvider)}. |
| 674 | * </p> |
Adam Powell | 3f476b3 | 2011-01-03 19:25:36 -0800 | [diff] [blame] | 675 | * |
| 676 | * @param resId Layout resource to use for presenting this item to the user. |
| 677 | * @return This Item so additional setters can be called. |
| 678 | * |
| 679 | * @see #setShowAsAction(int) |
| 680 | */ |
Tor Norbye | 7b9c912 | 2013-05-30 16:48:33 -0700 | [diff] [blame] | 681 | public MenuItem setActionView(@LayoutRes int resId); |
Adam Powell | 3f476b3 | 2011-01-03 19:25:36 -0800 | [diff] [blame] | 682 | |
| 683 | /** |
Adam Powell | cf78b3e | 2010-09-12 18:25:23 -0700 | [diff] [blame] | 684 | * Returns the currently set action view for this menu item. |
| 685 | * |
| 686 | * @return This item's action view |
| 687 | * |
| 688 | * @see #setActionView(View) |
| 689 | * @see #setShowAsAction(int) |
| 690 | */ |
| 691 | public View getActionView(); |
Adam Powell | 8d02dea | 2011-05-31 21:35:13 -0700 | [diff] [blame] | 692 | |
| 693 | /** |
Svetoslav Ganov | 51ac0e9 | 2011-06-17 13:45:13 -0700 | [diff] [blame] | 694 | * Sets the {@link ActionProvider} responsible for creating an action view if |
| 695 | * the item is placed on the action bar. The provider also provides a default |
| 696 | * action invoked if the item is placed in the overflow menu. |
| 697 | * <p> |
| 698 | * <strong>Note:</strong> Setting an action provider overrides the action view |
| 699 | * set via {@link #setActionView(int)} or {@link #setActionView(View)}. |
| 700 | * </p> |
| 701 | * |
| 702 | * @param actionProvider The action provider. |
| 703 | * @return This Item so additional setters can be called. |
| 704 | * |
| 705 | * @see ActionProvider |
| 706 | */ |
| 707 | public MenuItem setActionProvider(ActionProvider actionProvider); |
| 708 | |
| 709 | /** |
| 710 | * Gets the {@link ActionProvider}. |
| 711 | * |
| 712 | * @return The action provider. |
| 713 | * |
| 714 | * @see ActionProvider |
| 715 | * @see #setActionProvider(ActionProvider) |
| 716 | */ |
| 717 | public ActionProvider getActionProvider(); |
| 718 | |
| 719 | /** |
Adam Powell | 8d02dea | 2011-05-31 21:35:13 -0700 | [diff] [blame] | 720 | * Expand the action view associated with this menu item. |
| 721 | * The menu item must have an action view set, as well as |
| 722 | * the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. |
| 723 | * If a listener has been set using {@link #setOnActionExpandListener(OnActionExpandListener)} |
| 724 | * it will have its {@link OnActionExpandListener#onMenuItemActionExpand(MenuItem)} |
| 725 | * method invoked. The listener may return false from this method to prevent expanding |
| 726 | * the action view. |
| 727 | * |
| 728 | * @return true if the action view was expanded, false otherwise. |
| 729 | */ |
| 730 | public boolean expandActionView(); |
| 731 | |
| 732 | /** |
| 733 | * Collapse the action view associated with this menu item. |
| 734 | * The menu item must have an action view set, as well as the showAsAction flag |
| 735 | * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a listener has been set using |
| 736 | * {@link #setOnActionExpandListener(OnActionExpandListener)} it will have its |
| 737 | * {@link OnActionExpandListener#onMenuItemActionCollapse(MenuItem)} method invoked. |
| 738 | * The listener may return false from this method to prevent collapsing the action view. |
| 739 | * |
| 740 | * @return true if the action view was collapsed, false otherwise. |
| 741 | */ |
| 742 | public boolean collapseActionView(); |
| 743 | |
| 744 | /** |
| 745 | * Returns true if this menu item's action view has been expanded. |
| 746 | * |
| 747 | * @return true if the item's action view is expanded, false otherwise. |
| 748 | * |
| 749 | * @see #expandActionView() |
| 750 | * @see #collapseActionView() |
| 751 | * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW |
| 752 | * @see OnActionExpandListener |
| 753 | */ |
| 754 | public boolean isActionViewExpanded(); |
| 755 | |
| 756 | /** |
| 757 | * Set an {@link OnActionExpandListener} on this menu item to be notified when |
| 758 | * the associated action view is expanded or collapsed. The menu item must |
| 759 | * be configured to expand or collapse its action view using the flag |
| 760 | * {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. |
| 761 | * |
| 762 | * @param listener Listener that will respond to expand/collapse events |
| 763 | * @return This menu item instance for call chaining |
| 764 | */ |
| 765 | public MenuItem setOnActionExpandListener(OnActionExpandListener listener); |
Vladislav Kaznacheev | 7039cbc | 2017-01-04 10:15:31 -0800 | [diff] [blame] | 766 | |
| 767 | /** |
| 768 | * Change the content description associated with this menu item. |
| 769 | * |
| 770 | * @param contentDescription The new content description. |
| 771 | */ |
| 772 | default MenuItem setContentDescription(CharSequence contentDescription) { |
| 773 | return this; |
| 774 | } |
| 775 | |
| 776 | /** |
| 777 | * Retrieve the content description associated with this menu item. |
| 778 | * |
| 779 | * @return The content description. |
| 780 | */ |
| 781 | default CharSequence getContentDescription() { |
| 782 | return null; |
| 783 | } |
| 784 | |
| 785 | /** |
| 786 | * Change the tooltip text associated with this menu item. |
| 787 | * |
Vladislav Kaznacheev | 6a944ca | 2017-01-19 11:02:12 -0800 | [diff] [blame] | 788 | * @param tooltipText The new tooltip text. |
Vladislav Kaznacheev | 7039cbc | 2017-01-04 10:15:31 -0800 | [diff] [blame] | 789 | */ |
Vladislav Kaznacheev | 6a944ca | 2017-01-19 11:02:12 -0800 | [diff] [blame] | 790 | default MenuItem setTooltipText(CharSequence tooltipText) { |
Vladislav Kaznacheev | 7039cbc | 2017-01-04 10:15:31 -0800 | [diff] [blame] | 791 | return this; |
| 792 | } |
| 793 | |
| 794 | /** |
| 795 | * Retrieve the tooltip text associated with this menu item. |
| 796 | * |
| 797 | * @return The tooltip text. |
| 798 | */ |
Vladislav Kaznacheev | 6a944ca | 2017-01-19 11:02:12 -0800 | [diff] [blame] | 799 | default CharSequence getTooltipText() { |
Vladislav Kaznacheev | 7039cbc | 2017-01-04 10:15:31 -0800 | [diff] [blame] | 800 | return null; |
| 801 | } |
Siyamed Sinir | 484c2e2 | 2017-06-07 16:26:19 -0700 | [diff] [blame] | 802 | |
| 803 | /** |
Abodunrinwa Toki | 9c881f2 | 2017-10-16 21:05:41 +0100 | [diff] [blame] | 804 | * Returns true if {@link #setShowAsAction(int)} was set to {@link #SHOW_AS_ACTION_ALWAYS}. |
| 805 | * Default value is {@code false}. |
| 806 | * |
| 807 | * @hide |
| 808 | */ |
| 809 | default boolean requiresActionButton() { |
| 810 | return false; |
| 811 | } |
| 812 | |
| 813 | /** |
| 814 | * Returns true if {@link #setShowAsAction(int)} was set to {@link #SHOW_AS_ACTION_NEVER}. |
| 815 | * Default value is {@code true}. |
Siyamed Sinir | 484c2e2 | 2017-06-07 16:26:19 -0700 | [diff] [blame] | 816 | * |
| 817 | * @hide |
| 818 | */ |
| 819 | default boolean requiresOverflow() { |
Abodunrinwa Toki | 9c881f2 | 2017-10-16 21:05:41 +0100 | [diff] [blame] | 820 | return true; |
Siyamed Sinir | 484c2e2 | 2017-06-07 16:26:19 -0700 | [diff] [blame] | 821 | } |
Michael Wright | 7b69e05 | 2014-08-09 16:23:05 -0700 | [diff] [blame] | 822 | } |