/ABSherlock/src/com/actionbarsherlock/view/ActionProvider.java

  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
 17package com.actionbarsherlock.view;
 18
 19import android.content.Context;
 20import android.view.View;
 21
 22/**
 23 * This class is a mediator for accomplishing a given task, for example sharing a file.
 24 * It is responsible for creating a view that performs an action that accomplishes the task.
 25 * This class also implements other functions such a performing a default action.
 26 * <p>
 27 * An ActionProvider can be optionally specified for a {@link MenuItem} and in such a
 28 * case it will be responsible for creating the action view that appears in the
 29 * {@link android.app.ActionBar} as a substitute for the menu item when the item is
 30 * displayed as an action item. Also the provider is responsible for performing a
 31 * default action if a menu item placed on the overflow menu of the ActionBar is
 32 * selected and none of the menu item callbacks has handled the selection. For this
 33 * case the provider can also optionally provide a sub-menu for accomplishing the
 34 * task at hand.
 35 * </p>
 36 * <p>
 37 * There are two ways for using an action provider for creating and handling of action views:
 38 * <ul>
 39 * <li>
 40 * Setting the action provider on a {@link MenuItem} directly by calling
 41 * {@link MenuItem#setActionProvider(ActionProvider)}.
 42 * </li>
 43 * <li>
 44 * Declaring the action provider in the menu XML resource. For example:
 45 * <pre>
 46 * <code>
 47 *   &lt;item android:id="@+id/my_menu_item"
 48 *     android:title="Title"
 49 *     android:icon="@drawable/my_menu_item_icon"
 50 *     android:showAsAction="ifRoom"
 51 *     android:actionProviderClass="foo.bar.SomeActionProvider" /&gt;
 52 * </code>
 53 * </pre>
 54 * </li>
 55 * </ul>
 56 * </p>
 57 *
 58 * @see MenuItem#setActionProvider(ActionProvider)
 59 * @see MenuItem#getActionProvider()
 60 */
 61public abstract class ActionProvider {
 62    private SubUiVisibilityListener mSubUiVisibilityListener;
 63
 64    /**
 65     * Creates a new instance.
 66     *
 67     * @param context Context for accessing resources.
 68     */
 69    public ActionProvider(Context context) {
 70    }
 71
 72    /**
 73     * Factory method for creating new action views.
 74     *
 75     * @return A new action view.
 76     */
 77    public abstract View onCreateActionView();
 78
 79    /**
 80     * Performs an optional default action.
 81     * <p>
 82     * For the case of an action provider placed in a menu item not shown as an action this
 83     * method is invoked if previous callbacks for processing menu selection has handled
 84     * the event.
 85     * </p>
 86     * <p>
 87     * A menu item selection is processed in the following order:
 88     * <ul>
 89     * <li>
 90     * Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick
 91     *  MenuItem.OnMenuItemClickListener.onMenuItemClick}.
 92     * </li>
 93     * <li>
 94     * Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem)
 95     *  Activity.onOptionsItemSelected(MenuItem)}
 96     * </li>
 97     * <li>
 98     * Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem)
 99     *  Fragment.onOptionsItemSelected(MenuItem)}
100     * </li>
101     * <li>
102     * Launching the {@link android.content.Intent} set via
103     * {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)}
104     * </li>
105     * <li>
106     * Invoking this method.
107     * </li>
108     * </ul>
109     * </p>
110     * <p>
111     * The default implementation does not perform any action and returns false.
112     * </p>
113     */
114    public boolean onPerformDefaultAction() {
115        return false;
116    }
117
118    /**
119     * Determines if this ActionProvider has a submenu associated with it.
120     *
121     * <p>Associated submenus will be shown when an action view is not. This
122     * provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)}
123     * after the call to {@link #onPerformDefaultAction()} and before a submenu is
124     * displayed to the user.
125     *
126     * @return true if the item backed by this provider should have an associated submenu
127     */
128    public boolean hasSubMenu() {
129        return false;
130    }
131
132    /**
133     * Called to prepare an associated submenu for the menu item backed by this ActionProvider.
134     *
135     * <p>if {@link #hasSubMenu()} returns true, this method will be called when the
136     * menu item is selected to prepare the submenu for presentation to the user. Apps
137     * may use this to create or alter submenu content right before display.
138     *
139     * @param subMenu Submenu that will be displayed
140     */
141    public void onPrepareSubMenu(SubMenu subMenu) {
142    }
143
144    /**
145     * Notify the system that the visibility of an action view's sub-UI such as
146     * an anchored popup has changed. This will affect how other system
147     * visibility notifications occur.
148     *
149     * @hide Pending future API approval
150     */
151    public void subUiVisibilityChanged(boolean isVisible) {
152        if (mSubUiVisibilityListener != null) {
153            mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible);
154        }
155    }
156
157    /**
158     * @hide Internal use only
159     */
160    public void setSubUiVisibilityListener(SubUiVisibilityListener listener) {
161        mSubUiVisibilityListener = listener;
162    }
163
164    /**
165     * @hide Internal use only
166     */
167    public interface SubUiVisibilityListener {
168        public void onSubUiVisibilityChanged(boolean isVisible);
169    }
170}