actionbarsherlock/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
  17 package com.actionbarsherlock.view;
  18
  19 import android.content.Context;
  20 import 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  */
  61 public 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 }