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
17package android.support.v4.internal.view;
18
19import android.support.v4.view.ActionProvider;
20import android.support.v4.view.MenuItemCompat;
21import android.view.MenuItem;
22import android.view.View;
23
24/**
25 * Interface for direct access to a previously created menu item.
26 *
27 * This version extends the one available in the framework to ensures that any necessary
28 * elements added in later versions of the framework, are available for all platforms.
29 *
30 * @see android.view.MenuItem
31 * @hide
32 */
33public interface SupportMenuItem extends android.view.MenuItem {
34    /*
35    * These should be kept in sync with attrs.xml enum constants for showAsAction
36    */
37    /**
38     * Never show this item as a button in an Action Bar.
39     */
40    public static final int SHOW_AS_ACTION_NEVER = 0;
41    /**
42     * Show this item as a button in an Action Bar if the system decides there is room for it.
43     */
44    public static final int SHOW_AS_ACTION_IF_ROOM = 1;
45    /**
46     * Always show this item as a button in an Action Bar.
47     * Use sparingly! If too many items are set to always show in the Action Bar it can
48     * crowd the Action Bar and degrade the user experience on devices with smaller screens.
49     * A good rule of thumb is to have no more than 2 items set to always show at a time.
50     */
51    public static final int SHOW_AS_ACTION_ALWAYS = 2;
52
53    /**
54     * When this item is in the action bar, always show it with a text label even if it also has an
55     * icon specified.
56     */
57    public static final int SHOW_AS_ACTION_WITH_TEXT = 4;
58
59    /**
60     * This item's action view collapses to a normal menu item. When expanded, the action view
61     * temporarily takes over a larger segment of its container.
62     */
63    public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8;
64
65    /**
66     * Sets how this item should display in the presence of an Action Bar. The parameter actionEnum
67     * is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or
68     * {@link #SHOW_AS_ACTION_NEVER} should be used, and you may optionally OR the value with {@link
69     * #SHOW_AS_ACTION_WITH_TEXT}. SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as
70     * an action, it should be shown with a text label.
71     *
72     * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link
73     *                   #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}.
74     *                   SHOW_AS_ACTION_NEVER is the default.
75     * @see android.app.ActionBar
76     * @see #setActionView(View)
77     */
78    public void setShowAsAction(int actionEnum);
79
80    /**
81     * Sets how this item should display in the presence of an Action Bar.
82     * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS},
83     * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should
84     * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}.
85     * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action,
86     * it should be shown with a text label.
87     *
88     * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it
89     * returns the current MenuItem instance for call chaining.
90     *
91     * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link
92     *                   #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}.
93     *                   SHOW_AS_ACTION_NEVER is the default.
94     * @return This MenuItem instance for call chaining.
95     * @see android.app.ActionBar
96     * @see #setActionView(View)
97     */
98    public MenuItem setShowAsActionFlags(int actionEnum);
99
100    /**
101     * Set an action view for this menu item. An action view will be displayed in place
102     * of an automatically generated menu item element in the UI when this item is shown
103     * as an action within a parent.
104     *
105     * <p><strong>Note:</strong> Setting an action view overrides the action provider
106     * provider set via {@link #setSupportActionProvider(android.support.v4.view.ActionProvider)}. </p>
107     *
108     * @param view View to use for presenting this item to the user.
109     * @return This Item so additional setters can be called.
110     * @see #setShowAsAction(int)
111     */
112    public MenuItem setActionView(View view);
113
114    /**
115     * Set an action view for this menu item. An action view will be displayed in place
116     * of an automatically generated menu item element in the UI when this item is shown
117     * as an action within a parent.
118     *
119     * <p><strong>Note:</strong> Setting an action view overrides the action provider
120     * provider set via {@link #setSupportActionProvider(android.support.v4.view.ActionProvider)}. </p>
121     *
122     * @param resId Layout resource to use for presenting this item to the user.
123     * @return This Item so additional setters can be called.
124     * @see #setShowAsAction(int)
125     */
126    public MenuItem setActionView(int resId);
127
128    /**
129     * Returns the currently set action view for this menu item.
130     *
131     * @return This item's action view
132     * @see #setActionView(View)
133     * @see #setShowAsAction(int)
134     */
135    public View getActionView();
136
137    /**
138     * Sets the {@link android.support.v4.view.ActionProvider} responsible for creating an action view if
139     * the item is placed on the action bar. The provider also provides a default
140     * action invoked if the item is placed in the overflow menu.
141     *
142     * <p><strong>Note:</strong> Setting an action provider overrides the action view
143     * set via {@link #setActionView(int)} or {@link #setActionView(View)}.
144     * </p>
145     *
146     * @param actionProvider The action provider.
147     * @return This Item so additional setters can be called.
148     * @see android.support.v4.view.ActionProvider
149     */
150    public SupportMenuItem setSupportActionProvider(ActionProvider actionProvider);
151
152    /**
153     * Gets the {@link ActionProvider}.
154     *
155     * @return The action provider.
156     * @see ActionProvider
157     * @see #setSupportActionProvider(ActionProvider)
158     */
159    public ActionProvider getSupportActionProvider();
160
161    /**
162     * Expand the action view associated with this menu item. The menu item must have an action view
163     * set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a
164     * listener has been set using {@link #setSupportOnActionExpandListener(android.support.v4.view.MenuItemCompat.OnActionExpandListener)}
165     * it will have its {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener#onMenuItemActionExpand(MenuItem)} method
166     * invoked. The listener may return false from this method to prevent expanding the action view.
167     *
168     * @return true if the action view was expanded, false otherwise.
169     */
170    public boolean expandActionView();
171
172    /**
173     * Collapse the action view associated with this menu item. The menu item must have an action
174     * view set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a
175     * listener has been set using {@link #setSupportOnActionExpandListener(android.support.v4.view.MenuItemCompat.OnActionExpandListener)}
176     * it will have its {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener#onMenuItemActionCollapse(MenuItem)} method
177     * invoked. The listener may return false from this method to prevent collapsing the action
178     * view.
179     *
180     * @return true if the action view was collapsed, false otherwise.
181     */
182    public boolean collapseActionView();
183
184    /**
185     * Returns true if this menu item's action view has been expanded.
186     *
187     * @return true if the item's action view is expanded, false otherwise.
188     * @see #expandActionView()
189     * @see #collapseActionView()
190     * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW
191     * @see android.support.v4.view.MenuItemCompat.OnActionExpandListener
192     */
193    public boolean isActionViewExpanded();
194
195    /**
196     * Set an {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener} on this menu item to be notified when the associated
197     * action view is expanded or collapsed. The menu item must be configured to expand or collapse
198     * its action view using the flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}.
199     *
200     * @param listener Listener that will respond to expand/collapse events
201     * @return This menu item instance for call chaining
202     */
203    public SupportMenuItem setSupportOnActionExpandListener(MenuItemCompat.OnActionExpandListener listener);
204}