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 import android.annotation.StringRes; 21 import android.annotation.TestApi; 22 import android.graphics.Rect; 23 24 /** 25 * Represents a contextual mode of the user interface. Action modes can be used to provide 26 * alternative interaction modes and replace parts of the normal UI until finished. 27 * Examples of good action modes include text selection and contextual actions. 28 * <div class="special reference"> 29 * <h3>Developer Guides</h3> 30 * <p>For information about how to provide contextual actions with {@code ActionMode}, 31 * read the <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a> 32 * developer guide.</p> 33 * </div> 34 */ 35 public abstract class ActionMode { 36 37 /** 38 * The action mode is treated as a Primary mode. This is the default. 39 * Use with {@link #setType}. 40 */ 41 public static final int TYPE_PRIMARY = 0; 42 /** 43 * The action mode is treated as a Floating Toolbar. 44 * Use with {@link #setType}. 45 */ 46 public static final int TYPE_FLOATING = 1; 47 48 /** 49 * Default value to hide the action mode for 50 * {@link ViewConfiguration#getDefaultActionModeHideDuration()}. 51 */ 52 public static final int DEFAULT_HIDE_DURATION = -1; 53 54 private Object mTag; 55 private boolean mTitleOptionalHint; 56 private int mType = TYPE_PRIMARY; 57 58 /** 59 * Set a tag object associated with this ActionMode. 60 * 61 * <p>Like the tag available to views, this allows applications to associate arbitrary 62 * data with an ActionMode for later reference. 63 * 64 * @param tag Tag to associate with this ActionMode 65 * 66 * @see #getTag() 67 */ 68 public void setTag(Object tag) { 69 mTag = tag; 70 } 71 72 /** 73 * Retrieve the tag object associated with this ActionMode. 74 * 75 * <p>Like the tag available to views, this allows applications to associate arbitrary 76 * data with an ActionMode for later reference. 77 * 78 * @return Tag associated with this ActionMode 79 * 80 * @see #setTag(Object) 81 */ 82 public Object getTag() { 83 return mTag; 84 } 85 86 /** 87 * Set the title of the action mode. This method will have no visible effect if 88 * a custom view has been set. 89 * 90 * @param title Title string to set 91 * 92 * @see #setTitle(int) 93 * @see #setCustomView(View) 94 */ 95 public abstract void setTitle(CharSequence title); 96 97 /** 98 * Set the title of the action mode. This method will have no visible effect if 99 * a custom view has been set. 100 * 101 * @param resId Resource ID of a string to set as the title 102 * 103 * @see #setTitle(CharSequence) 104 * @see #setCustomView(View) 105 */ 106 public abstract void setTitle(@StringRes int resId); 107 108 /** 109 * Set the subtitle of the action mode. This method will have no visible effect if 110 * a custom view has been set. 111 * 112 * @param subtitle Subtitle string to set 113 * 114 * @see #setSubtitle(int) 115 * @see #setCustomView(View) 116 */ 117 public abstract void setSubtitle(CharSequence subtitle); 118 119 /** 120 * Set the subtitle of the action mode. This method will have no visible effect if 121 * a custom view has been set. 122 * 123 * @param resId Resource ID of a string to set as the subtitle 124 * 125 * @see #setSubtitle(CharSequence) 126 * @see #setCustomView(View) 127 */ 128 public abstract void setSubtitle(@StringRes int resId); 129 130 /** 131 * Set whether or not the title/subtitle display for this action mode 132 * is optional. 133 * 134 * <p>In many cases the supplied title for an action mode is merely 135 * meant to add context and is not strictly required for the action 136 * mode to be useful. If the title is optional, the system may choose 137 * to hide the title entirely rather than truncate it due to a lack 138 * of available space.</p> 139 * 140 * <p>Note that this is merely a hint; the underlying implementation 141 * may choose to ignore this setting under some circumstances.</p> 142 * 143 * @param titleOptional true if the title only presents optional information. 144 */ 145 public void setTitleOptionalHint(boolean titleOptional) { 146 mTitleOptionalHint = titleOptional; 147 } 148 149 /** 150 * @return true if this action mode has been given a hint to consider the 151 * title/subtitle display to be optional. 152 * 153 * @see #setTitleOptionalHint(boolean) 154 * @see #isTitleOptional() 155 */ 156 public boolean getTitleOptionalHint() { 157 return mTitleOptionalHint; 158 } 159 160 /** 161 * @return true if this action mode considers the title and subtitle fields 162 * as optional. Optional titles may not be displayed to the user. 163 */ 164 public boolean isTitleOptional() { 165 return false; 166 } 167 168 /** 169 * Set a custom view for this action mode. The custom view will take the place of 170 * the title and subtitle. Useful for things like search boxes. 171 * 172 * @param view Custom view to use in place of the title/subtitle. 173 * 174 * @see #setTitle(CharSequence) 175 * @see #setSubtitle(CharSequence) 176 */ 177 public abstract void setCustomView(View view); 178 179 /** 180 * Set a type for this action mode. This will affect how the system renders the action mode if 181 * it has to. 182 * 183 * @param type One of {@link #TYPE_PRIMARY} or {@link #TYPE_FLOATING}. 184 */ 185 public void setType(int type) { 186 mType = type; 187 } 188 189 /** 190 * Returns the type for this action mode. 191 * 192 * @return One of {@link #TYPE_PRIMARY} or {@link #TYPE_FLOATING}. 193 */ 194 public int getType() { 195 return mType; 196 } 197 198 /** 199 * Invalidate the action mode and refresh menu content. The mode's 200 * {@link ActionMode.Callback} will have its 201 * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called. 202 * If it returns true the menu will be scanned for updated content and any relevant changes 203 * will be reflected to the user. 204 */ 205 public abstract void invalidate(); 206 207 /** 208 * Invalidate the content rect associated to this ActionMode. This only makes sense for 209 * action modes that support dynamic positioning on the screen, and provides a more efficient 210 * way to reposition it without invalidating the whole action mode. 211 * 212 * @see Callback2#onGetContentRect(ActionMode, View, Rect) . 213 */ 214 public void invalidateContentRect() {} 215 216 /** 217 * Hide the action mode view from obstructing the content below for a short duration. 218 * This only makes sense for action modes that support dynamic positioning on the screen. 219 * If this method is called again before the hide duration expires, the later hide call will 220 * cancel the former and then take effect. 221 * NOTE that there is an internal limit to how long the mode can be hidden for. It's typically 222 * about a few seconds. 223 * 224 * @param duration The number of milliseconds to hide for. 225 * @see #DEFAULT_HIDE_DURATION 226 */ 227 public void hide(long duration) {} 228 229 /** 230 * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will 231 * have its {@link Callback#onDestroyActionMode(ActionMode)} method called. 232 */ 233 public abstract void finish(); 234 235 /** 236 * Returns the menu of actions that this action mode presents. 237 * @return The action mode's menu. 238 */ 239 public abstract Menu getMenu(); 240 241 /** 242 * Returns the current title of this action mode. 243 * @return Title text 244 */ 245 public abstract CharSequence getTitle(); 246 247 /** 248 * Returns the current subtitle of this action mode. 249 * @return Subtitle text 250 */ 251 public abstract CharSequence getSubtitle(); 252 253 /** 254 * Returns the current custom view for this action mode. 255 * @return The current custom view 256 */ 257 public abstract View getCustomView(); 258 259 /** 260 * Returns a {@link MenuInflater} with the ActionMode's context. 261 */ 262 public abstract MenuInflater getMenuInflater(); 263 264 /** 265 * Called when the window containing the view that started this action mode gains or loses 266 * focus. 267 * 268 * @param hasWindowFocus True if the window containing the view that started this action mode 269 * now has focus, false otherwise. 270 * 271 */ 272 public void onWindowFocusChanged(boolean hasWindowFocus) {} 273 274 /** 275 * Returns whether the UI presenting this action mode can take focus or not. 276 * This is used by internal components within the framework that would otherwise 277 * present an action mode UI that requires focus, such as an EditText as a custom view. 278 * 279 * @return true if the UI used to show this action mode can take focus 280 * @hide Internal use only 281 */ 282 @TestApi 283 public boolean isUiFocusable() { 284 return true; 285 } 286 287 /** 288 * Callback interface for action modes. Supplied to 289 * {@link View#startActionMode(Callback)}, a Callback 290 * configures and handles events raised by a user's interaction with an action mode. 291 * 292 * <p>An action mode's lifecycle is as follows: 293 * <ul> 294 * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial 295 * creation</li> 296 * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation 297 * and any time the {@link ActionMode} is invalidated</li> 298 * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a 299 * contextual action button is clicked</li> 300 * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode 301 * is closed</li> 302 * </ul> 303 */ 304 public interface Callback { 305 /** 306 * Called when action mode is first created. The menu supplied will be used to 307 * generate action buttons for the action mode. 308 * 309 * @param mode ActionMode being created 310 * @param menu Menu used to populate action buttons 311 * @return true if the action mode should be created, false if entering this 312 * mode should be aborted. 313 */ 314 public boolean onCreateActionMode(ActionMode mode, Menu menu); 315 316 /** 317 * Called to refresh an action mode's action menu whenever it is invalidated. 318 * 319 * @param mode ActionMode being prepared 320 * @param menu Menu used to populate action buttons 321 * @return true if the menu or action mode was updated, false otherwise. 322 */ 323 public boolean onPrepareActionMode(ActionMode mode, Menu menu); 324 325 /** 326 * Called to report a user click on an action button. 327 * 328 * @param mode The current ActionMode 329 * @param item The item that was clicked 330 * @return true if this callback handled the event, false if the standard MenuItem 331 * invocation should continue. 332 */ 333 public boolean onActionItemClicked(ActionMode mode, MenuItem item); 334 335 /** 336 * Called when an action mode is about to be exited and destroyed. 337 * 338 * @param mode The current ActionMode being destroyed 339 */ 340 public void onDestroyActionMode(ActionMode mode); 341 } 342 343 /** 344 * Extension of {@link ActionMode.Callback} to provide content rect information. This is 345 * required for ActionModes with dynamic positioning such as the ones with type 346 * {@link ActionMode#TYPE_FLOATING} to ensure the positioning doesn't obscure app content. If 347 * an app fails to provide a subclass of this class, a default implementation will be used. 348 */ 349 public static abstract class Callback2 implements ActionMode.Callback { 350 351 /** 352 * Called when an ActionMode needs to be positioned on screen, potentially occluding view 353 * content. Note this may be called on a per-frame basis. 354 * 355 * @param mode The ActionMode that requires positioning. 356 * @param view The View that originated the ActionMode, in whose coordinates the Rect should 357 * be provided. 358 * @param outRect The Rect to be populated with the content position. Use this to specify 359 * where the content in your app lives within the given view. This will be used 360 * to avoid occluding the given content Rect with the created ActionMode. 361 */ 362 public void onGetContentRect(ActionMode mode, View view, Rect outRect) { 363 if (view != null) { 364 outRect.set(0, 0, view.getWidth(), view.getHeight()); 365 } else { 366 outRect.set(0, 0, 0, 0); 367 } 368 } 369 370 } 371 } 372
