1 /*
2  * Copyright (C) 2013 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 androidx.core.internal.view;
18 
19 import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
20 
21 import android.content.res.ColorStateList;
22 import android.graphics.PorterDuff;
23 import android.graphics.drawable.Drawable;
24 import android.view.MenuItem;
25 import android.view.View;
26 
27 import androidx.annotation.RestrictTo;
28 import androidx.core.view.ActionProvider;
29 
30 /**
31  * Interface for direct access to a previously created menu item.
32  *
33  * This version extends the one available in the framework to ensures that any necessary
34  * elements added in later versions of the framework, are available for all platforms.
35  *
36  * @see android.view.MenuItem
37  * @hide
38  */
39 @RestrictTo(LIBRARY_GROUP)
40 public interface SupportMenuItem extends android.view.MenuItem {
41     /*
42     * These should be kept in sync with attrs.xml enum constants for showAsAction
43     */
44     /**
45      * Never show this item as a button in an Action Bar.
46      */
47     int SHOW_AS_ACTION_NEVER = 0;
48     /**
49      * Show this item as a button in an Action Bar if the system decides there is room for it.
50      */
51     int SHOW_AS_ACTION_IF_ROOM = 1;
52     /**
53      * Always show this item as a button in an Action Bar.
54      * Use sparingly! If too many items are set to always show in the Action Bar it can
55      * crowd the Action Bar and degrade the user experience on devices with smaller screens.
56      * A good rule of thumb is to have no more than 2 items set to always show at a time.
57      */
58     int SHOW_AS_ACTION_ALWAYS = 2;
59 
60     /**
61      * When this item is in the action bar, always show it with a text label even if it also has an
62      * icon specified.
63      */
64     int SHOW_AS_ACTION_WITH_TEXT = 4;
65 
66     /**
67      * This item's action view collapses to a normal menu item. When expanded, the action view
68      * temporarily takes over a larger segment of its container.
69      */
70     int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8;
71 
72     /**
73      * Sets how this item should display in the presence of an Action Bar. The parameter actionEnum
74      * is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or
75      * {@link #SHOW_AS_ACTION_NEVER} should be used, and you may optionally OR the value with {@link
76      * #SHOW_AS_ACTION_WITH_TEXT}. SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as
77      * an action, it should be shown with a text label.
78      *
79      * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link
80      *                   #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}.
81      *                   SHOW_AS_ACTION_NEVER is the default.
82      * @see android.app.ActionBar
83      * @see #setActionView(View)
84      */
85     @Override
setShowAsAction(int actionEnum)86     void setShowAsAction(int actionEnum);
87 
88     /**
89      * Sets how this item should display in the presence of an Action Bar.
90      * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS},
91      * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should
92      * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}.
93      * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action,
94      * it should be shown with a text label.
95      *
96      * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it
97      * returns the current MenuItem instance for call chaining.
98      *
99      * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link
100      *                   #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}.
101      *                   SHOW_AS_ACTION_NEVER is the default.
102      * @return This MenuItem instance for call chaining.
103      * @see android.app.ActionBar
104      * @see #setActionView(View)
105      */
106     @Override
setShowAsActionFlags(int actionEnum)107     MenuItem setShowAsActionFlags(int actionEnum);
108 
109     /**
110      * Set an action view for this menu item. An action view will be displayed in place
111      * of an automatically generated menu item element in the UI when this item is shown
112      * as an action within a parent.
113      *
114      * <p><strong>Note:</strong> Setting an action view overrides the action provider
115      * provider set via {@link #setSupportActionProvider(androidx.core.view.ActionProvider)}. </p>
116      *
117      * @param view View to use for presenting this item to the user.
118      * @return This Item so additional setters can be called.
119      * @see #setShowAsAction(int)
120      */
121     @Override
setActionView(View view)122     MenuItem setActionView(View view);
123 
124     /**
125      * Set an action view for this menu item. An action view will be displayed in place
126      * of an automatically generated menu item element in the UI when this item is shown
127      * as an action within a parent.
128      *
129      * <p><strong>Note:</strong> Setting an action view overrides the action provider
130      * provider set via {@link #setSupportActionProvider(androidx.core.view.ActionProvider)}. </p>
131      *
132      * @param resId Layout resource to use for presenting this item to the user.
133      * @return This Item so additional setters can be called.
134      * @see #setShowAsAction(int)
135      */
136     @Override
setActionView(int resId)137     MenuItem setActionView(int resId);
138 
139     /**
140      * Returns the currently set action view for this menu item.
141      *
142      * @return This item's action view
143      * @see #setActionView(View)
144      * @see #setShowAsAction(int)
145      */
146     @Override
getActionView()147     View getActionView();
148 
149     /**
150      * Sets the {@link androidx.core.view.ActionProvider} responsible for creating an action view if
151      * the item is placed on the action bar. The provider also provides a default
152      * action invoked if the item is placed in the overflow menu.
153      *
154      * <p><strong>Note:</strong> Setting an action provider overrides the action view
155      * set via {@link #setActionView(int)} or {@link #setActionView(View)}.
156      * </p>
157      *
158      * @param actionProvider The action provider.
159      * @return This Item so additional setters can be called.
160      * @see androidx.core.view.ActionProvider
161      */
setSupportActionProvider(ActionProvider actionProvider)162     SupportMenuItem setSupportActionProvider(ActionProvider actionProvider);
163 
164     /**
165      * Gets the {@link ActionProvider}.
166      *
167      * @return The action provider.
168      * @see ActionProvider
169      * @see #setSupportActionProvider(ActionProvider)
170      */
getSupportActionProvider()171     ActionProvider getSupportActionProvider();
172 
173     /**
174      * Expand the action view associated with this menu item. The menu item must have an action view
175      * set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a
176      * listener has been set using
177      * {@link #setSupportOnActionExpandListener(MenuItem.OnActionExpandListener)}
178      * it will have its {@link MenuItem.OnActionExpandListener#onMenuItemActionExpand(MenuItem)}
179      * method invoked. The listener may return false from this method to prevent expanding the
180      * action view.
181      *
182      * @return true if the action view was expanded, false otherwise.
183      */
184     @Override
expandActionView()185     boolean expandActionView();
186 
187     /**
188      * Collapse the action view associated with this menu item. The menu item must have an action
189      * view set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a
190      * listener has been set using
191      * {@link #setSupportOnActionExpandListener(MenuItem.OnActionExpandListener)}
192      * it will have its {@link MenuItem.OnActionExpandListener#onMenuItemActionCollapse(MenuItem)}
193      * method invoked. The listener may return false from this method to prevent collapsing the
194      * action view.
195      *
196      * @return true if the action view was collapsed, false otherwise.
197      */
198     @Override
collapseActionView()199     boolean collapseActionView();
200 
201     /**
202      * Returns true if this menu item's action view has been expanded.
203      *
204      * @return true if the item's action view is expanded, false otherwise.
205      * @see #expandActionView()
206      * @see #collapseActionView()
207      * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW
208      * @see MenuItem.OnActionExpandListener
209      */
210     @Override
isActionViewExpanded()211     boolean isActionViewExpanded();
212 
213     /**
214      * Change the content description associated with this menu item.
215      *
216      * @param contentDescription The new content description.
217      * @return This menu item instance for call chaining.
218      */
219     @Override
setContentDescription(CharSequence contentDescription)220     SupportMenuItem setContentDescription(CharSequence contentDescription);
221 
222     /**
223      * Retrieve the content description associated with this menu item.
224      *
225      * @return The content description.
226      */
227     @Override
getContentDescription()228     CharSequence getContentDescription();
229 
230     /**
231      * Change the tooltip text associated with this menu item.
232      *
233      * @param tooltipText The new tooltip text.
234      * @return This menu item instance for call chaining.
235      */
236     @Override
setTooltipText(CharSequence tooltipText)237     SupportMenuItem setTooltipText(CharSequence tooltipText);
238 
239     /**
240      * Retrieve the tooltip text associated with this menu item.
241      *
242      * @return The tooltip text.
243      */
244     @Override
getTooltipText()245     CharSequence getTooltipText();
246 
247     /**
248      * Change both the numeric and alphabetic shortcut associated with this
249      * item. Note that the shortcut will be triggered when the key that
250      * generates the given character is pressed along with the corresponding
251      * modifier key. Also note that case is not significant and that alphabetic
252      * shortcut characters will be handled in lower case.
253      * <p>
254      * See {@link Menu} for the menu types that support shortcuts.
255      *
256      * @param numericChar The numeric shortcut key. This is the shortcut when
257      *        using a numeric (e.g., 12-key) keyboard.
258      * @param numericModifiers The numeric modifier associated with the shortcut. It should
259      *        be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON},
260      *        {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON},
261      *        {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}.
262      * @param alphaChar The alphabetic shortcut key. This is the shortcut when
263      *        using a keyboard with alphabetic keys.
264      * @param alphaModifiers The alphabetic modifier associated with the shortcut. It should
265      *        be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON},
266      *        {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON},
267      *        {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}.
268      * @return This Item so additional setters can be called.
269      */
270     @Override
setShortcut(char numericChar, char alphaChar, int numericModifiers, int alphaModifiers)271     MenuItem setShortcut(char numericChar, char alphaChar, int numericModifiers,
272             int alphaModifiers);
273 
274     /**
275      * Change the numeric shortcut and modifiers associated with this item.
276      * <p>
277      * See {@link Menu} for the menu types that support shortcuts.
278      *
279      * @param numericChar The numeric shortcut key.  This is the shortcut when
280      *                 using a 12-key (numeric) keyboard.
281      * @param numericModifiers The modifier associated with the shortcut. It should
282      *        be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON},
283      *        {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON},
284      *        {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}.
285      * @return This Item so additional setters can be called.
286      */
287     @Override
setNumericShortcut(char numericChar, int numericModifiers)288     MenuItem setNumericShortcut(char numericChar, int numericModifiers);
289 
290     /**
291      * Return the modifiers for this menu item's numeric (12-key) shortcut.
292      * The modifier is a combination of {@link KeyEvent#META_META_ON},
293      * {@link KeyEvent#META_CTRL_ON}, {@link KeyEvent#META_ALT_ON},
294      * {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_SYM_ON},
295      * {@link KeyEvent#META_FUNCTION_ON}.
296      * For example, {@link KeyEvent#META_FUNCTION_ON}|{@link KeyEvent#META_CTRL_ON}
297      *
298      * @return Modifier associated with the numeric shortcut.
299      */
300     @Override
getNumericModifiers()301     int getNumericModifiers();
302 
303     /**
304      * Change the alphabetic shortcut associated with this item. The shortcut
305      * will be triggered when the key that generates the given character is
306      * pressed along with the modifier keys. Case is not significant and shortcut
307      * characters will be displayed in lower case. Note that menu items with
308      * the characters '\b' or '\n' as shortcuts will get triggered by the
309      * Delete key or Carriage Return key, respectively.
310      * <p>
311      * See {@link Menu} for the menu types that support shortcuts.
312      *
313      * @param alphaChar The alphabetic shortcut key. This is the shortcut when
314      *        using a keyboard with alphabetic keys.
315      * @param alphaModifiers The modifier associated with the shortcut. It should
316      *        be a combination of {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_CTRL_ON},
317      *        {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_SHIFT_ON},
318      *        {@link KeyEvent#META_SYM_ON}, {@link KeyEvent#META_FUNCTION_ON}.
319      * @return This Item so additional setters can be called.
320      */
321     @Override
setAlphabeticShortcut(char alphaChar, int alphaModifiers)322     MenuItem setAlphabeticShortcut(char alphaChar, int alphaModifiers);
323 
324     /**
325      * Return the modifier for this menu item's alphabetic shortcut.
326      * The modifier is a combination of {@link KeyEvent#META_META_ON},
327      * {@link KeyEvent#META_CTRL_ON}, {@link KeyEvent#META_ALT_ON},
328      * {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_SYM_ON},
329      * {@link KeyEvent#META_FUNCTION_ON}.
330      * For example, {@link KeyEvent#META_FUNCTION_ON}|{@link KeyEvent#META_CTRL_ON}
331      *
332      * @return Modifier associated with the keyboard shortcut.
333      */
334     @Override
getAlphabeticModifiers()335     int getAlphabeticModifiers();
336 
337     /**
338      * Applies a tint to this item's icon. Does not modify the
339      * current tint mode, which is {@link PorterDuff.Mode#SRC_IN} by default.
340      * <p>
341      * Subsequent calls to {@link MenuItem#setIcon(Drawable)} or {@link MenuItem#setIcon(int)} will
342      * automatically mutate the icon and apply the specified tint and
343      * tint mode.
344      *
345      * @param tint the tint to apply, may be {@code null} to clear tint
346      *
347      * @see #getIconTintList()
348      */
349     @Override
setIconTintList(ColorStateList tint)350     MenuItem setIconTintList(ColorStateList tint);
351 
352     /**
353      * @return the tint applied to this item's icon
354      * @see #setIconTintList(ColorStateList)
355      */
356     @Override
getIconTintList()357     ColorStateList getIconTintList();
358 
359     /**
360      * Specifies the blending mode used to apply the tint specified by
361      * {@link #setIconTintList(ColorStateList)} to this item's icon. The default mode is
362      * {@link PorterDuff.Mode#SRC_IN}.
363      *
364      * @param tintMode the blending mode used to apply the tint, may be
365      *                 {@code null} to clear tint
366      * @see #setIconTintList(ColorStateList)
367      */
368     @Override
setIconTintMode(PorterDuff.Mode tintMode)369     MenuItem setIconTintMode(PorterDuff.Mode tintMode);
370 
371     /**
372      * Returns the blending mode used to apply the tint to this item's icon, if specified.
373      *
374      * @return the blending mode used to apply the tint to this item's icon
375      * @see #setIconTintMode(PorterDuff.Mode)
376      */
377     @Override
getIconTintMode()378     PorterDuff.Mode getIconTintMode();
379 }