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

https://bitbucket.org/ayastrebov/android-actionbarsherlock · Java · 170 lines · 28 code · 11 blank · 131 comment · 2 complexity · 0b51291265d81f1e6054078d6185cfd1 MD5 · raw file

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