1 /*
2  * Copyright (C) 2011 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.compat.annotation.UnsupportedAppUsage;
20 import android.content.Context;
21 import android.util.Log;
22 
23 /**
24  * An ActionProvider defines rich menu interaction in a single component.
25  * ActionProvider can generate action views for use in the action bar,
26  * dynamically populate submenus of a MenuItem, and handle default menu
27  * item invocations.
28  *
29  * <p>An ActionProvider can be optionally specified for a {@link MenuItem} and will be
30  * responsible for creating the action view that appears in the {@link android.app.ActionBar}
31  * in place of a simple button in the bar. When the menu item is presented in a way that
32  * does not allow custom action views, (e.g. in an overflow menu,) the ActionProvider
33  * can perform a default action.</p>
34  *
35  * <p>There are two ways to use an action provider:
36  * <ul>
37  * <li>
38  * Set the action provider on a {@link MenuItem} directly by calling
39  * {@link MenuItem#setActionProvider(ActionProvider)}.
40  * </li>
41  * <li>
42  * Declare the action provider in an XML menu resource. For example:
43  * <pre>
44  * <code>
45  *   &lt;item android:id="@+id/my_menu_item"
46  *     android:title="Title"
47  *     android:icon="@drawable/my_menu_item_icon"
48  *     android:showAsAction="ifRoom"
49  *     android:actionProviderClass="foo.bar.SomeActionProvider" /&gt;
50  * </code>
51  * </pre>
52  * </li>
53  * </ul>
54  * </p>
55  *
56  * @see MenuItem#setActionProvider(ActionProvider)
57  * @see MenuItem#getActionProvider()
58  */
59 public abstract class ActionProvider {
60     private static final String TAG = "ActionProvider";
61     private SubUiVisibilityListener mSubUiVisibilityListener;
62     private VisibilityListener mVisibilityListener;
63 
64     /**
65      * Creates a new instance. ActionProvider classes should always implement a
66      * constructor that takes a single Context parameter for inflating from menu XML.
67      *
68      * @param context Context for accessing resources.
69      */
ActionProvider(Context context)70     public ActionProvider(Context context) {
71     }
72 
73     /**
74      * Factory method called by the Android framework to create new action views.
75      *
76      * <p>This method has been deprecated in favor of {@link #onCreateActionView(MenuItem)}.
77      * Newer apps that wish to support platform versions prior to API 16 should also
78      * implement this method to return a valid action view.</p>
79      *
80      * @return A new action view.
81      *
82      * @deprecated use {@link #onCreateActionView(MenuItem)}
83      */
84     @Deprecated
onCreateActionView()85     public abstract View onCreateActionView();
86 
87     /**
88      * Factory method called by the Android framework to create new action views.
89      * This method returns a new action view for the given MenuItem.
90      *
91      * <p>If your ActionProvider implementation overrides the deprecated no-argument overload
92      * {@link #onCreateActionView()}, overriding this method for devices running API 16 or later
93      * is recommended but optional. The default implementation calls {@link #onCreateActionView()}
94      * for compatibility with applications written for older platform versions.</p>
95      *
96      * @param forItem MenuItem to create the action view for
97      * @return the new action view
98      */
onCreateActionView(MenuItem forItem)99     public View onCreateActionView(MenuItem forItem) {
100         return onCreateActionView();
101     }
102 
103     /**
104      * The result of this method determines whether or not {@link #isVisible()} will be used
105      * by the {@link MenuItem} this ActionProvider is bound to help determine its visibility.
106      *
107      * @return true if this ActionProvider overrides the visibility of the MenuItem
108      *         it is bound to, false otherwise. The default implementation returns false.
109      * @see #isVisible()
110      */
overridesItemVisibility()111     public boolean overridesItemVisibility() {
112         return false;
113     }
114 
115     /**
116      * If {@link #overridesItemVisibility()} returns true, the return value of this method
117      * will help determine the visibility of the {@link MenuItem} this ActionProvider is bound to.
118      *
119      * <p>If the MenuItem's visibility is explicitly set to false by the application,
120      * the MenuItem will not be shown, even if this method returns true.</p>
121      *
122      * @return true if the MenuItem this ActionProvider is bound to is visible, false if
123      *         it is invisible. The default implementation returns true.
124      */
isVisible()125     public boolean isVisible() {
126         return true;
127     }
128 
129     /**
130      * If this ActionProvider is associated with an item in a menu,
131      * refresh the visibility of the item based on {@link #overridesItemVisibility()} and
132      * {@link #isVisible()}. If {@link #overridesItemVisibility()} returns false, this call
133      * will have no effect.
134      */
refreshVisibility()135     public void refreshVisibility() {
136         if (mVisibilityListener != null && overridesItemVisibility()) {
137             mVisibilityListener.onActionProviderVisibilityChanged(isVisible());
138         }
139     }
140 
141     /**
142      * Performs an optional default action.
143      * <p>
144      * For the case of an action provider placed in a menu item not shown as an action this
145      * method is invoked if previous callbacks for processing menu selection has handled
146      * the event.
147      * </p>
148      * <p>
149      * A menu item selection is processed in the following order:
150      * <ul>
151      * <li>
152      * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick
153      *  MenuItem.OnMenuItemClickListener.onMenuItemClick}.
154      * </li>
155      * <li>
156      * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem)
157      *  Activity.onOptionsItemSelected(MenuItem)}
158      * </li>
159      * <li>
160      * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem)
161      *  Fragment.onOptionsItemSelected(MenuItem)}
162      * </li>
163      * <li>
164      * Launching the {@link android.content.Intent} set via
165      * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)}
166      * </li>
167      * <li>
168      * Invoking this method.
169      * </li>
170      * </ul>
171      * </p>
172      * <p>
173      * The default implementation does not perform any action and returns false.
174      * </p>
175      */
onPerformDefaultAction()176     public boolean onPerformDefaultAction() {
177         return false;
178     }
179 
180     /**
181      * Determines if this ActionProvider has a submenu associated with it.
182      *
183      * <p>Associated submenus will be shown when an action view is not. This
184      * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)}
185      * after the call to {@link #onPerformDefaultAction()} and before a submenu is
186      * displayed to the user.
187      *
188      * @return true if the item backed by this provider should have an associated submenu
189      */
hasSubMenu()190     public boolean hasSubMenu() {
191         return false;
192     }
193 
194     /**
195      * Called to prepare an associated submenu for the menu item backed by this ActionProvider.
196      *
197      * <p>if {@link #hasSubMenu()} returns true, this method will be called when the
198      * menu item is selected to prepare the submenu for presentation to the user. Apps
199      * may use this to create or alter submenu content right before display.
200      *
201      * @param subMenu Submenu that will be displayed
202      */
onPrepareSubMenu(SubMenu subMenu)203     public void onPrepareSubMenu(SubMenu subMenu) {
204     }
205 
206     /**
207      * Notify the system that the visibility of an action view's sub-UI such as
208      * an anchored popup has changed. This will affect how other system
209      * visibility notifications occur.
210      *
211      * @hide Pending future API approval
212      */
subUiVisibilityChanged(boolean isVisible)213     public void subUiVisibilityChanged(boolean isVisible) {
214         if (mSubUiVisibilityListener != null) {
215             mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible);
216         }
217     }
218 
219     /**
220      * @hide Internal use only
221      */
222     @UnsupportedAppUsage
setSubUiVisibilityListener(SubUiVisibilityListener listener)223     public void setSubUiVisibilityListener(SubUiVisibilityListener listener) {
224         mSubUiVisibilityListener = listener;
225     }
226 
227     /**
228      * Set a listener to be notified when this ActionProvider's overridden visibility changes.
229      * This should only be used by MenuItem implementations.
230      *
231      * @param listener listener to set
232      */
setVisibilityListener(VisibilityListener listener)233     public void setVisibilityListener(VisibilityListener listener) {
234         if (mVisibilityListener != null) {
235             Log.w(TAG, "setVisibilityListener: Setting a new ActionProvider.VisibilityListener " +
236                     "when one is already set. Are you reusing this " + getClass().getSimpleName() +
237                     " instance while it is still in use somewhere else?");
238         }
239         mVisibilityListener = listener;
240     }
241 
242     /**
243      * @hide
244      */
245     @UnsupportedAppUsage
reset()246     public void reset() {
247         mVisibilityListener = null;
248         mSubUiVisibilityListener = null;
249     }
250 
251     /**
252      * @hide Internal use only
253      */
254     public interface SubUiVisibilityListener {
onSubUiVisibilityChanged(boolean isVisible)255         public void onSubUiVisibilityChanged(boolean isVisible);
256     }
257 
258     /**
259      * Listens to changes in visibility as reported by {@link ActionProvider#refreshVisibility()}.
260      *
261      * @see ActionProvider#overridesItemVisibility()
262      * @see ActionProvider#isVisible()
263      */
264     public interface VisibilityListener {
onActionProviderVisibilityChanged(boolean isVisible)265         public void onActionProviderVisibilityChanged(boolean isVisible);
266     }
267 }
268