1 /* 2 * Copyright (C) 2010 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 android.view; 18 19 20 /** 21 * Represents a contextual mode of the user interface. Action modes can be used for 22 * modal interactions with content and replace parts of the normal UI until finished. 23 * Examples of good action modes include selection modes, search, content editing, etc. 24 */ 25 public abstract class ActionMode { 26 private Object mTag; 27 28 /** 29 * Set a tag object associated with this ActionMode. 30 * 31 * <p>Like the tag available to views, this allows applications to associate arbitrary 32 * data with an ActionMode for later reference. 33 * 34 * @param tag Tag to associate with this ActionMode 35 * 36 * @see #getTag() 37 */ setTag(Object tag)38 public void setTag(Object tag) { 39 mTag = tag; 40 } 41 42 /** 43 * Retrieve the tag object associated with this ActionMode. 44 * 45 * <p>Like the tag available to views, this allows applications to associate arbitrary 46 * data with an ActionMode for later reference. 47 * 48 * @return Tag associated with this ActionMode 49 * 50 * @see #setTag(Object) 51 */ getTag()52 public Object getTag() { 53 return mTag; 54 } 55 56 /** 57 * Set the title of the action mode. This method will have no visible effect if 58 * a custom view has been set. 59 * 60 * @param title Title string to set 61 * 62 * @see #setTitle(int) 63 * @see #setCustomView(View) 64 */ setTitle(CharSequence title)65 public abstract void setTitle(CharSequence title); 66 67 /** 68 * Set the title of the action mode. This method will have no visible effect if 69 * a custom view has been set. 70 * 71 * @param resId Resource ID of a string to set as the title 72 * 73 * @see #setTitle(CharSequence) 74 * @see #setCustomView(View) 75 */ setTitle(int resId)76 public abstract void setTitle(int resId); 77 78 /** 79 * Set the subtitle of the action mode. This method will have no visible effect if 80 * a custom view has been set. 81 * 82 * @param subtitle Subtitle string to set 83 * 84 * @see #setSubtitle(int) 85 * @see #setCustomView(View) 86 */ setSubtitle(CharSequence subtitle)87 public abstract void setSubtitle(CharSequence subtitle); 88 89 /** 90 * Set the subtitle of the action mode. This method will have no visible effect if 91 * a custom view has been set. 92 * 93 * @param resId Resource ID of a string to set as the subtitle 94 * 95 * @see #setSubtitle(CharSequence) 96 * @see #setCustomView(View) 97 */ setSubtitle(int resId)98 public abstract void setSubtitle(int resId); 99 100 /** 101 * Set a custom view for this action mode. The custom view will take the place of 102 * the title and subtitle. Useful for things like search boxes. 103 * 104 * @param view Custom view to use in place of the title/subtitle. 105 * 106 * @see #setTitle(CharSequence) 107 * @see #setSubtitle(CharSequence) 108 */ setCustomView(View view)109 public abstract void setCustomView(View view); 110 111 /** 112 * Invalidate the action mode and refresh menu content. The mode's 113 * {@link ActionMode.Callback} will have its 114 * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called. 115 * If it returns true the menu will be scanned for updated content and any relevant changes 116 * will be reflected to the user. 117 */ invalidate()118 public abstract void invalidate(); 119 120 /** 121 * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will 122 * have its {@link Callback#onDestroyActionMode(ActionMode)} method called. 123 */ finish()124 public abstract void finish(); 125 126 /** 127 * Returns the menu of actions that this action mode presents. 128 * @return The action mode's menu. 129 */ getMenu()130 public abstract Menu getMenu(); 131 132 /** 133 * Returns the current title of this action mode. 134 * @return Title text 135 */ getTitle()136 public abstract CharSequence getTitle(); 137 138 /** 139 * Returns the current subtitle of this action mode. 140 * @return Subtitle text 141 */ getSubtitle()142 public abstract CharSequence getSubtitle(); 143 144 /** 145 * Returns the current custom view for this action mode. 146 * @return The current custom view 147 */ getCustomView()148 public abstract View getCustomView(); 149 150 /** 151 * Returns a {@link MenuInflater} with the ActionMode's context. 152 */ getMenuInflater()153 public abstract MenuInflater getMenuInflater(); 154 155 /** 156 * Returns whether the UI presenting this action mode can take focus or not. 157 * This is used by internal components within the framework that would otherwise 158 * present an action mode UI that requires focus, such as an EditText as a custom view. 159 * 160 * @return true if the UI used to show this action mode can take focus 161 * @hide Internal use only 162 */ isUiFocusable()163 public boolean isUiFocusable() { 164 return true; 165 } 166 167 /** 168 * Callback interface for action modes. Supplied to 169 * {@link View#startActionMode(Callback)}, a Callback 170 * configures and handles events raised by a user's interaction with an action mode. 171 * 172 * <p>An action mode's lifecycle is as follows: 173 * <ul> 174 * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial 175 * creation</li> 176 * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation 177 * and any time the {@link ActionMode} is invalidated</li> 178 * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a 179 * contextual action button is clicked</li> 180 * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode 181 * is closed</li> 182 * </ul> 183 */ 184 public interface Callback { 185 /** 186 * Called when action mode is first created. The menu supplied will be used to 187 * generate action buttons for the action mode. 188 * 189 * @param mode ActionMode being created 190 * @param menu Menu used to populate action buttons 191 * @return true if the action mode should be created, false if entering this 192 * mode should be aborted. 193 */ onCreateActionMode(ActionMode mode, Menu menu)194 public boolean onCreateActionMode(ActionMode mode, Menu menu); 195 196 /** 197 * Called to refresh an action mode's action menu whenever it is invalidated. 198 * 199 * @param mode ActionMode being prepared 200 * @param menu Menu used to populate action buttons 201 * @return true if the menu or action mode was updated, false otherwise. 202 */ onPrepareActionMode(ActionMode mode, Menu menu)203 public boolean onPrepareActionMode(ActionMode mode, Menu menu); 204 205 /** 206 * Called to report a user click on an action button. 207 * 208 * @param mode The current ActionMode 209 * @param item The item that was clicked 210 * @return true if this callback handled the event, false if the standard MenuItem 211 * invocation should continue. 212 */ onActionItemClicked(ActionMode mode, MenuItem item)213 public boolean onActionItemClicked(ActionMode mode, MenuItem item); 214 215 /** 216 * Called when an action mode is about to be exited and destroyed. 217 * 218 * @param mode The current ActionMode being destroyed 219 */ onDestroyActionMode(ActionMode mode)220 public void onDestroyActionMode(ActionMode mode); 221 } 222 }