diff options
Diffstat (limited to 'android/view/ActionProvider.java')
| -rw-r--r-- | android/view/ActionProvider.java | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/android/view/ActionProvider.java b/android/view/ActionProvider.java new file mode 100644 index 00000000..353b4c26 --- /dev/null +++ b/android/view/ActionProvider.java @@ -0,0 +1,264 @@ +/* + * Copyright (C) 2011 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.view; + +import android.content.Context; +import android.util.Log; + +/** + * An ActionProvider defines rich menu interaction in a single component. + * ActionProvider can generate action views for use in the action bar, + * dynamically populate submenus of a MenuItem, and handle default menu + * item invocations. + * + * <p>An ActionProvider can be optionally specified for a {@link MenuItem} and will be + * responsible for creating the action view that appears in the {@link android.app.ActionBar} + * in place of a simple button in the bar. When the menu item is presented in a way that + * does not allow custom action views, (e.g. in an overflow menu,) the ActionProvider + * can perform a default action.</p> + * + * <p>There are two ways to use an action provider: + * <ul> + * <li> + * Set the action provider on a {@link MenuItem} directly by calling + * {@link MenuItem#setActionProvider(ActionProvider)}. + * </li> + * <li> + * Declare the action provider in an XML menu resource. For example: + * <pre> + * <code> + * <item android:id="@+id/my_menu_item" + * android:title="Title" + * android:icon="@drawable/my_menu_item_icon" + * android:showAsAction="ifRoom" + * android:actionProviderClass="foo.bar.SomeActionProvider" /> + * </code> + * </pre> + * </li> + * </ul> + * </p> + * + * @see MenuItem#setActionProvider(ActionProvider) + * @see MenuItem#getActionProvider() + */ +public abstract class ActionProvider { + private static final String TAG = "ActionProvider"; + private SubUiVisibilityListener mSubUiVisibilityListener; + private VisibilityListener mVisibilityListener; + + /** + * Creates a new instance. ActionProvider classes should always implement a + * constructor that takes a single Context parameter for inflating from menu XML. + * + * @param context Context for accessing resources. + */ + public ActionProvider(Context context) { + } + + /** + * Factory method called by the Android framework to create new action views. + * + * <p>This method has been deprecated in favor of {@link #onCreateActionView(MenuItem)}. + * Newer apps that wish to support platform versions prior to API 16 should also + * implement this method to return a valid action view.</p> + * + * @return A new action view. + * + * @deprecated use {@link #onCreateActionView(MenuItem)} + */ + @Deprecated + public abstract View onCreateActionView(); + + /** + * Factory method called by the Android framework to create new action views. + * This method returns a new action view for the given MenuItem. + * + * <p>If your ActionProvider implementation overrides the deprecated no-argument overload + * {@link #onCreateActionView()}, overriding this method for devices running API 16 or later + * is recommended but optional. The default implementation calls {@link #onCreateActionView()} + * for compatibility with applications written for older platform versions.</p> + * + * @param forItem MenuItem to create the action view for + * @return the new action view + */ + public View onCreateActionView(MenuItem forItem) { + return onCreateActionView(); + } + + /** + * The result of this method determines whether or not {@link #isVisible()} will be used + * by the {@link MenuItem} this ActionProvider is bound to help determine its visibility. + * + * @return true if this ActionProvider overrides the visibility of the MenuItem + * it is bound to, false otherwise. The default implementation returns false. + * @see #isVisible() + */ + public boolean overridesItemVisibility() { + return false; + } + + /** + * If {@link #overridesItemVisibility()} returns true, the return value of this method + * will help determine the visibility of the {@link MenuItem} this ActionProvider is bound to. + * + * <p>If the MenuItem's visibility is explicitly set to false by the application, + * the MenuItem will not be shown, even if this method returns true.</p> + * + * @return true if the MenuItem this ActionProvider is bound to is visible, false if + * it is invisible. The default implementation returns true. + */ + public boolean isVisible() { + return true; + } + + /** + * If this ActionProvider is associated with an item in a menu, + * refresh the visibility of the item based on {@link #overridesItemVisibility()} and + * {@link #isVisible()}. If {@link #overridesItemVisibility()} returns false, this call + * will have no effect. + */ + public void refreshVisibility() { + if (mVisibilityListener != null && overridesItemVisibility()) { + mVisibilityListener.onActionProviderVisibilityChanged(isVisible()); + } + } + + /** + * Performs an optional default action. + * <p> + * For the case of an action provider placed in a menu item not shown as an action this + * method is invoked if previous callbacks for processing menu selection has handled + * the event. + * </p> + * <p> + * A menu item selection is processed in the following order: + * <ul> + * <li> + * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick + * MenuItem.OnMenuItemClickListener.onMenuItemClick}. + * </li> + * <li> + * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem) + * Activity.onOptionsItemSelected(MenuItem)} + * </li> + * <li> + * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem) + * Fragment.onOptionsItemSelected(MenuItem)} + * </li> + * <li> + * Launching the {@link android.content.Intent} set via + * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)} + * </li> + * <li> + * Invoking this method. + * </li> + * </ul> + * </p> + * <p> + * The default implementation does not perform any action and returns false. + * </p> + */ + public boolean onPerformDefaultAction() { + return false; + } + + /** + * Determines if this ActionProvider has a submenu associated with it. + * + * <p>Associated submenus will be shown when an action view is not. This + * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)} + * after the call to {@link #onPerformDefaultAction()} and before a submenu is + * displayed to the user. + * + * @return true if the item backed by this provider should have an associated submenu + */ + public boolean hasSubMenu() { + return false; + } + + /** + * Called to prepare an associated submenu for the menu item backed by this ActionProvider. + * + * <p>if {@link #hasSubMenu()} returns true, this method will be called when the + * menu item is selected to prepare the submenu for presentation to the user. Apps + * may use this to create or alter submenu content right before display. + * + * @param subMenu Submenu that will be displayed + */ + public void onPrepareSubMenu(SubMenu subMenu) { + } + + /** + * Notify the system that the visibility of an action view's sub-UI such as + * an anchored popup has changed. This will affect how other system + * visibility notifications occur. + * + * @hide Pending future API approval + */ + public void subUiVisibilityChanged(boolean isVisible) { + if (mSubUiVisibilityListener != null) { + mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible); + } + } + + /** + * @hide Internal use only + */ + public void setSubUiVisibilityListener(SubUiVisibilityListener listener) { + mSubUiVisibilityListener = listener; + } + + /** + * Set a listener to be notified when this ActionProvider's overridden visibility changes. + * This should only be used by MenuItem implementations. + * + * @param listener listener to set + */ + public void setVisibilityListener(VisibilityListener listener) { + if (mVisibilityListener != null) { + Log.w(TAG, "setVisibilityListener: Setting a new ActionProvider.VisibilityListener " + + "when one is already set. Are you reusing this " + getClass().getSimpleName() + + " instance while it is still in use somewhere else?"); + } + mVisibilityListener = listener; + } + + /** + * @hide + */ + public void reset() { + mVisibilityListener = null; + mSubUiVisibilityListener = null; + } + + /** + * @hide Internal use only + */ + public interface SubUiVisibilityListener { + public void onSubUiVisibilityChanged(boolean isVisible); + } + + /** + * Listens to changes in visibility as reported by {@link ActionProvider#refreshVisibility()}. + * + * @see ActionProvider#overridesItemVisibility() + * @see ActionProvider#isVisible() + */ + public interface VisibilityListener { + public void onActionProviderVisibilityChanged(boolean isVisible); + } +} |