--- /dev/null
+/*\r
+ * Copyright (C) 2010 The Android Open Source Project\r
+ *\r
+ * Licensed under the Apache License, Version 2.0 (the "License");\r
+ * you may not use this file except in compliance with the License.\r
+ * You may obtain a copy of the License at\r
+ *\r
+ * http://www.apache.org/licenses/LICENSE-2.0\r
+ *\r
+ * Unless required by applicable law or agreed to in writing, software\r
+ * distributed under the License is distributed on an "AS IS" BASIS,\r
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ * See the License for the specific language governing permissions and\r
+ * limitations under the License.\r
+ */\r
+\r
+package com.actionbarsherlock.view;\r
+\r
+import android.view.View;\r
+\r
+\r
+/**\r
+ * Represents a contextual mode of the user interface. Action modes can be used for\r
+ * modal interactions with content and replace parts of the normal UI until finished.\r
+ * Examples of good action modes include selection modes, search, content editing, etc.\r
+ */\r
+public abstract class ActionMode {\r
+ private Object mTag;\r
+\r
+ /**\r
+ * Set a tag object associated with this ActionMode.\r
+ *\r
+ * <p>Like the tag available to views, this allows applications to associate arbitrary\r
+ * data with an ActionMode for later reference.\r
+ *\r
+ * @param tag Tag to associate with this ActionMode\r
+ *\r
+ * @see #getTag()\r
+ */\r
+ public void setTag(Object tag) {\r
+ mTag = tag;\r
+ }\r
+\r
+ /**\r
+ * Retrieve the tag object associated with this ActionMode.\r
+ *\r
+ * <p>Like the tag available to views, this allows applications to associate arbitrary\r
+ * data with an ActionMode for later reference.\r
+ *\r
+ * @return Tag associated with this ActionMode\r
+ *\r
+ * @see #setTag(Object)\r
+ */\r
+ public Object getTag() {\r
+ return mTag;\r
+ }\r
+\r
+ /**\r
+ * Set the title of the action mode. This method will have no visible effect if\r
+ * a custom view has been set.\r
+ *\r
+ * @param title Title string to set\r
+ *\r
+ * @see #setTitle(int)\r
+ * @see #setCustomView(View)\r
+ */\r
+ public abstract void setTitle(CharSequence title);\r
+\r
+ /**\r
+ * Set the title of the action mode. This method will have no visible effect if\r
+ * a custom view has been set.\r
+ *\r
+ * @param resId Resource ID of a string to set as the title\r
+ *\r
+ * @see #setTitle(CharSequence)\r
+ * @see #setCustomView(View)\r
+ */\r
+ public abstract void setTitle(int resId);\r
+\r
+ /**\r
+ * Set the subtitle of the action mode. This method will have no visible effect if\r
+ * a custom view has been set.\r
+ *\r
+ * @param subtitle Subtitle string to set\r
+ *\r
+ * @see #setSubtitle(int)\r
+ * @see #setCustomView(View)\r
+ */\r
+ public abstract void setSubtitle(CharSequence subtitle);\r
+\r
+ /**\r
+ * Set the subtitle of the action mode. This method will have no visible effect if\r
+ * a custom view has been set.\r
+ *\r
+ * @param resId Resource ID of a string to set as the subtitle\r
+ *\r
+ * @see #setSubtitle(CharSequence)\r
+ * @see #setCustomView(View)\r
+ */\r
+ public abstract void setSubtitle(int resId);\r
+\r
+ /**\r
+ * Set a custom view for this action mode. The custom view will take the place of\r
+ * the title and subtitle. Useful for things like search boxes.\r
+ *\r
+ * @param view Custom view to use in place of the title/subtitle.\r
+ *\r
+ * @see #setTitle(CharSequence)\r
+ * @see #setSubtitle(CharSequence)\r
+ */\r
+ public abstract void setCustomView(View view);\r
+\r
+ /**\r
+ * Invalidate the action mode and refresh menu content. The mode's\r
+ * {@link ActionMode.Callback} will have its\r
+ * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called.\r
+ * If it returns true the menu will be scanned for updated content and any relevant changes\r
+ * will be reflected to the user.\r
+ */\r
+ public abstract void invalidate();\r
+\r
+ /**\r
+ * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will\r
+ * have its {@link Callback#onDestroyActionMode(ActionMode)} method called.\r
+ */\r
+ public abstract void finish();\r
+\r
+ /**\r
+ * Returns the menu of actions that this action mode presents.\r
+ * @return The action mode's menu.\r
+ */\r
+ public abstract Menu getMenu();\r
+\r
+ /**\r
+ * Returns the current title of this action mode.\r
+ * @return Title text\r
+ */\r
+ public abstract CharSequence getTitle();\r
+\r
+ /**\r
+ * Returns the current subtitle of this action mode.\r
+ * @return Subtitle text\r
+ */\r
+ public abstract CharSequence getSubtitle();\r
+\r
+ /**\r
+ * Returns the current custom view for this action mode.\r
+ * @return The current custom view\r
+ */\r
+ public abstract View getCustomView();\r
+\r
+ /**\r
+ * Returns a {@link MenuInflater} with the ActionMode's context.\r
+ */\r
+ public abstract MenuInflater getMenuInflater();\r
+\r
+ /**\r
+ * Returns whether the UI presenting this action mode can take focus or not.\r
+ * This is used by internal components within the framework that would otherwise\r
+ * present an action mode UI that requires focus, such as an EditText as a custom view.\r
+ *\r
+ * @return true if the UI used to show this action mode can take focus\r
+ * @hide Internal use only\r
+ */\r
+ public boolean isUiFocusable() {\r
+ return true;\r
+ }\r
+\r
+ /**\r
+ * Callback interface for action modes. Supplied to\r
+ * {@link View#startActionMode(Callback)}, a Callback\r
+ * configures and handles events raised by a user's interaction with an action mode.\r
+ *\r
+ * <p>An action mode's lifecycle is as follows:\r
+ * <ul>\r
+ * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial\r
+ * creation</li>\r
+ * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation\r
+ * and any time the {@link ActionMode} is invalidated</li>\r
+ * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a\r
+ * contextual action button is clicked</li>\r
+ * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode\r
+ * is closed</li>\r
+ * </ul>\r
+ */\r
+ public interface Callback {\r
+ /**\r
+ * Called when action mode is first created. The menu supplied will be used to\r
+ * generate action buttons for the action mode.\r
+ *\r
+ * @param mode ActionMode being created\r
+ * @param menu Menu used to populate action buttons\r
+ * @return true if the action mode should be created, false if entering this\r
+ * mode should be aborted.\r
+ */\r
+ public boolean onCreateActionMode(ActionMode mode, Menu menu);\r
+\r
+ /**\r
+ * Called to refresh an action mode's action menu whenever it is invalidated.\r
+ *\r
+ * @param mode ActionMode being prepared\r
+ * @param menu Menu used to populate action buttons\r
+ * @return true if the menu or action mode was updated, false otherwise.\r
+ */\r
+ public boolean onPrepareActionMode(ActionMode mode, Menu menu);\r
+\r
+ /**\r
+ * Called to report a user click on an action button.\r
+ *\r
+ * @param mode The current ActionMode\r
+ * @param item The item that was clicked\r
+ * @return true if this callback handled the event, false if the standard MenuItem\r
+ * invocation should continue.\r
+ */\r
+ public boolean onActionItemClicked(ActionMode mode, MenuItem item);\r
+\r
+ /**\r
+ * Called when an action mode is about to be exited and destroyed.\r
+ *\r
+ * @param mode The current ActionMode being destroyed\r
+ */\r
+ public void onDestroyActionMode(ActionMode mode);\r
+ }\r
+}
\ No newline at end of file