Java tutorial
/* * 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.annotation.UnsupportedAppUsage; 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 */ @UnsupportedAppUsage 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 */ @UnsupportedAppUsage 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); } }