ActionMode.java revision 5e0959393426371dadef2c7905d5c915a1ac2dd4
16e34636749217654f43221885afb7a29bb5ca96aAdam Powell/* 26e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Copyright (C) 2010 The Android Open Source Project 36e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 46e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Licensed under the Apache License, Version 2.0 (the "License"); 56e34636749217654f43221885afb7a29bb5ca96aAdam Powell * you may not use this file except in compliance with the License. 66e34636749217654f43221885afb7a29bb5ca96aAdam Powell * You may obtain a copy of the License at 76e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 86e34636749217654f43221885afb7a29bb5ca96aAdam Powell * http://www.apache.org/licenses/LICENSE-2.0 96e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 106e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Unless required by applicable law or agreed to in writing, software 116e34636749217654f43221885afb7a29bb5ca96aAdam Powell * distributed under the License is distributed on an "AS IS" BASIS, 126e34636749217654f43221885afb7a29bb5ca96aAdam Powell * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 136e34636749217654f43221885afb7a29bb5ca96aAdam Powell * See the License for the specific language governing permissions and 146e34636749217654f43221885afb7a29bb5ca96aAdam Powell * limitations under the License. 156e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 166e34636749217654f43221885afb7a29bb5ca96aAdam Powell 176e34636749217654f43221885afb7a29bb5ca96aAdam Powellpackage android.view; 186e34636749217654f43221885afb7a29bb5ca96aAdam Powell 196e34636749217654f43221885afb7a29bb5ca96aAdam Powell 206e34636749217654f43221885afb7a29bb5ca96aAdam Powell/** 215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * Represents a contextual mode of the user interface. Action modes can be used to provide 225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * alternative interaction modes and replace parts of the normal UI until finished. 235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * Examples of good action modes include text selection and contextual actions. 245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * <div class="special reference"> 255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * <h3>Developer Guides</h3> 265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * <p>For information about how to provide contextual actions with {@code ActionMode}, 275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * read the <a href="{@docRoot}guide/topics/ui/menu.html#context-menu">Menus</a> 285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * developer guide.</p> 295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main * </div> 306e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 316e34636749217654f43221885afb7a29bb5ca96aAdam Powellpublic abstract class ActionMode { 32f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell private Object mTag; 33f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell 34f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell /** 35f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * Set a tag object associated with this ActionMode. 36f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * 37f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * <p>Like the tag available to views, this allows applications to associate arbitrary 38f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * data with an ActionMode for later reference. 39f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * 40f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * @param tag Tag to associate with this ActionMode 41f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * 42f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * @see #getTag() 43f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell */ 44f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell public void setTag(Object tag) { 45f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell mTag = tag; 46f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell } 47f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell 48f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell /** 49f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * Retrieve the tag object associated with this ActionMode. 50f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * 51f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * <p>Like the tag available to views, this allows applications to associate arbitrary 52f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * data with an ActionMode for later reference. 53f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * 54f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * @return Tag associated with this ActionMode 55f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * 56f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell * @see #setTag(Object) 57f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell */ 58f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell public Object getTag() { 59f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell return mTag; 60f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell } 61f178737f823cf22d9a07df6f51071b7189a95e7eAdam Powell 626e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 636e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Set the title of the action mode. This method will have no visible effect if 646e34636749217654f43221885afb7a29bb5ca96aAdam Powell * a custom view has been set. 656e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 666e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param title Title string to set 676e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 68c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @see #setTitle(int) 696e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @see #setCustomView(View) 706e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 716e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract void setTitle(CharSequence title); 726e34636749217654f43221885afb7a29bb5ca96aAdam Powell 736e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 74c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * Set the title of the action mode. This method will have no visible effect if 75c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * a custom view has been set. 76c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * 77c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @param resId Resource ID of a string to set as the title 78c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * 79c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @see #setTitle(CharSequence) 80c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @see #setCustomView(View) 81c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell */ 82c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell public abstract void setTitle(int resId); 83c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell 84c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell /** 856e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Set the subtitle of the action mode. This method will have no visible effect if 866e34636749217654f43221885afb7a29bb5ca96aAdam Powell * a custom view has been set. 876e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 886e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param subtitle Subtitle string to set 896e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 90c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @see #setSubtitle(int) 916e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @see #setCustomView(View) 926e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 936e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract void setSubtitle(CharSequence subtitle); 946e34636749217654f43221885afb7a29bb5ca96aAdam Powell 956e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 96c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * Set the subtitle of the action mode. This method will have no visible effect if 97c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * a custom view has been set. 98c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * 99c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @param resId Resource ID of a string to set as the subtitle 100c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * 101c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @see #setSubtitle(CharSequence) 102c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell * @see #setCustomView(View) 103c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell */ 104c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell public abstract void setSubtitle(int resId); 105c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell 106c9ae2a24dc1fa274ca0916c91a2e9a2764ba4bb3Adam Powell /** 1076e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Set a custom view for this action mode. The custom view will take the place of 1086e34636749217654f43221885afb7a29bb5ca96aAdam Powell * the title and subtitle. Useful for things like search boxes. 1096e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 1106e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param view Custom view to use in place of the title/subtitle. 1116e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 1126e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @see #setTitle(CharSequence) 1136e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @see #setSubtitle(CharSequence) 1146e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1156e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract void setCustomView(View view); 1166e34636749217654f43221885afb7a29bb5ca96aAdam Powell 1176e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1186e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Invalidate the action mode and refresh menu content. The mode's 1196e34636749217654f43221885afb7a29bb5ca96aAdam Powell * {@link ActionMode.Callback} will have its 1206e34636749217654f43221885afb7a29bb5ca96aAdam Powell * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called. 1216e34636749217654f43221885afb7a29bb5ca96aAdam Powell * If it returns true the menu will be scanned for updated content and any relevant changes 1226e34636749217654f43221885afb7a29bb5ca96aAdam Powell * will be reflected to the user. 1236e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1246e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract void invalidate(); 1256e34636749217654f43221885afb7a29bb5ca96aAdam Powell 1266e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1276e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will 1286e34636749217654f43221885afb7a29bb5ca96aAdam Powell * have its {@link Callback#onDestroyActionMode(ActionMode)} method called. 1296e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1306e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract void finish(); 1316e34636749217654f43221885afb7a29bb5ca96aAdam Powell 1326e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1336e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Returns the menu of actions that this action mode presents. 1346e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @return The action mode's menu. 1356e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1366e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract Menu getMenu(); 1376e34636749217654f43221885afb7a29bb5ca96aAdam Powell 1386e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1396e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Returns the current title of this action mode. 1406e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @return Title text 1416e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1426e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract CharSequence getTitle(); 1436e34636749217654f43221885afb7a29bb5ca96aAdam Powell 1446e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1456e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Returns the current subtitle of this action mode. 1466e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @return Subtitle text 1476e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1486e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract CharSequence getSubtitle(); 1496e34636749217654f43221885afb7a29bb5ca96aAdam Powell 1506e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1516e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Returns the current custom view for this action mode. 1526e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @return The current custom view 1536e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1546e34636749217654f43221885afb7a29bb5ca96aAdam Powell public abstract View getCustomView(); 1556e34636749217654f43221885afb7a29bb5ca96aAdam Powell 1566e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1579168f0b170c6a99371ae46e7d3f5d66c8c4c930dAdam Powell * Returns a {@link MenuInflater} with the ActionMode's context. 1589168f0b170c6a99371ae46e7d3f5d66c8c4c930dAdam Powell */ 1599168f0b170c6a99371ae46e7d3f5d66c8c4c930dAdam Powell public abstract MenuInflater getMenuInflater(); 1609168f0b170c6a99371ae46e7d3f5d66c8c4c930dAdam Powell 1619168f0b170c6a99371ae46e7d3f5d66c8c4c930dAdam Powell /** 162f8419a0299680ed580975b0fcb758990b4367db8Adam Powell * Returns whether the UI presenting this action mode can take focus or not. 163f8419a0299680ed580975b0fcb758990b4367db8Adam Powell * This is used by internal components within the framework that would otherwise 164f8419a0299680ed580975b0fcb758990b4367db8Adam Powell * present an action mode UI that requires focus, such as an EditText as a custom view. 165f8419a0299680ed580975b0fcb758990b4367db8Adam Powell * 166f8419a0299680ed580975b0fcb758990b4367db8Adam Powell * @return true if the UI used to show this action mode can take focus 167f8419a0299680ed580975b0fcb758990b4367db8Adam Powell * @hide Internal use only 168f8419a0299680ed580975b0fcb758990b4367db8Adam Powell */ 169f8419a0299680ed580975b0fcb758990b4367db8Adam Powell public boolean isUiFocusable() { 170f8419a0299680ed580975b0fcb758990b4367db8Adam Powell return true; 171f8419a0299680ed580975b0fcb758990b4367db8Adam Powell } 172f8419a0299680ed580975b0fcb758990b4367db8Adam Powell 173f8419a0299680ed580975b0fcb758990b4367db8Adam Powell /** 1746e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Callback interface for action modes. Supplied to 1756e34636749217654f43221885afb7a29bb5ca96aAdam Powell * {@link View#startActionMode(Callback)}, a Callback 1766e34636749217654f43221885afb7a29bb5ca96aAdam Powell * configures and handles events raised by a user's interaction with an action mode. 1776e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 1786e34636749217654f43221885afb7a29bb5ca96aAdam Powell * <p>An action mode's lifecycle is as follows: 1796e34636749217654f43221885afb7a29bb5ca96aAdam Powell * <ul> 1806e34636749217654f43221885afb7a29bb5ca96aAdam Powell * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial 1816e34636749217654f43221885afb7a29bb5ca96aAdam Powell * creation</li> 1826e34636749217654f43221885afb7a29bb5ca96aAdam Powell * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation 1836e34636749217654f43221885afb7a29bb5ca96aAdam Powell * and any time the {@link ActionMode} is invalidated</li> 1846e34636749217654f43221885afb7a29bb5ca96aAdam Powell * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a 1856e34636749217654f43221885afb7a29bb5ca96aAdam Powell * contextual action button is clicked</li> 1866e34636749217654f43221885afb7a29bb5ca96aAdam Powell * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode 1876e34636749217654f43221885afb7a29bb5ca96aAdam Powell * is closed</li> 1886e34636749217654f43221885afb7a29bb5ca96aAdam Powell * </ul> 1896e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 1906e34636749217654f43221885afb7a29bb5ca96aAdam Powell public interface Callback { 1916e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 1926e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Called when action mode is first created. The menu supplied will be used to 1936e34636749217654f43221885afb7a29bb5ca96aAdam Powell * generate action buttons for the action mode. 1946e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 1956e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param mode ActionMode being created 1966e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param menu Menu used to populate action buttons 1976e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @return true if the action mode should be created, false if entering this 1986e34636749217654f43221885afb7a29bb5ca96aAdam Powell * mode should be aborted. 1996e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 2006e34636749217654f43221885afb7a29bb5ca96aAdam Powell public boolean onCreateActionMode(ActionMode mode, Menu menu); 2016e34636749217654f43221885afb7a29bb5ca96aAdam Powell 2026e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 2036e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Called to refresh an action mode's action menu whenever it is invalidated. 2046e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 2056e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param mode ActionMode being prepared 2066e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param menu Menu used to populate action buttons 2076e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @return true if the menu or action mode was updated, false otherwise. 2086e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 2096e34636749217654f43221885afb7a29bb5ca96aAdam Powell public boolean onPrepareActionMode(ActionMode mode, Menu menu); 2106e34636749217654f43221885afb7a29bb5ca96aAdam Powell 2116e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 2126e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Called to report a user click on an action button. 2136e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 2146e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param mode The current ActionMode 2156e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param item The item that was clicked 2166e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @return true if this callback handled the event, false if the standard MenuItem 2176e34636749217654f43221885afb7a29bb5ca96aAdam Powell * invocation should continue. 2186e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 2196e34636749217654f43221885afb7a29bb5ca96aAdam Powell public boolean onActionItemClicked(ActionMode mode, MenuItem item); 2206e34636749217654f43221885afb7a29bb5ca96aAdam Powell 2216e34636749217654f43221885afb7a29bb5ca96aAdam Powell /** 2226e34636749217654f43221885afb7a29bb5ca96aAdam Powell * Called when an action mode is about to be exited and destroyed. 2236e34636749217654f43221885afb7a29bb5ca96aAdam Powell * 2246e34636749217654f43221885afb7a29bb5ca96aAdam Powell * @param mode The current ActionMode being destroyed 2256e34636749217654f43221885afb7a29bb5ca96aAdam Powell */ 2266e34636749217654f43221885afb7a29bb5ca96aAdam Powell public void onDestroyActionMode(ActionMode mode); 2276e34636749217654f43221885afb7a29bb5ca96aAdam Powell } 2286e34636749217654f43221885afb7a29bb5ca96aAdam Powell}